From 19163e79a35c772bdfb2245b03a9a53f749112d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?kleines=20Filmr=C3=B6llchen?= Date: Wed, 11 Sep 2024 16:20:33 +0200 Subject: [PATCH] Everywhere: Format Markdown with prettier These are the exact changes necessary to get the next commit to pass pre-commit checks. --- Base/usr/share/man/man1/Applications.md | 56 +- .../man/man1/Applications/3DFileViewer.md | 36 +- Base/usr/share/man/man1/Applications/About.md | 2 +- .../share/man/man1/Applications/Assistant.md | 8 +- .../share/man/man1/Applications/Browser.md | 6 +- .../usr/share/man/man1/Applications/CatDog.md | 10 +- .../man1/Applications/CertificateSettings.md | 5 +- .../man/man1/Applications/CharacterMap.md | 4 +- Base/usr/share/man/man1/Applications/Eyes.md | 14 +- .../share/man/man1/Applications/FontEditor.md | 27 +- .../man/man1/Applications/GMLPlayground.md | 5 +- Base/usr/share/man/man1/Applications/Help.md | 9 +- .../share/man/man1/Applications/HexEditor.md | 9 +- .../man/man1/Applications/ImageViewer.md | 6 +- .../share/man/man1/Applications/Magnifier.md | 2 +- Base/usr/share/man/man1/Applications/Mail.md | 3 +- Base/usr/share/man/man1/Applications/Maps.md | 10 +- .../share/man/man1/Applications/PixelPaint.md | 149 ++-- .../share/man/man1/Applications/Profiler.md | 8 +- .../share/man/man1/Applications/SQLStudio.md | 4 +- .../share/man/man1/Applications/Screenshot.md | 10 +- .../share/man/man1/Applications/Terminal.md | 28 +- .../share/man/man1/Applications/TextEditor.md | 4 +- Base/usr/share/man/man1/Shell.md | 14 +- Base/usr/share/man/man1/abench.md | 4 +- Base/usr/share/man/man1/aconv.md | 36 +- Base/usr/share/man/man1/adjtime.md | 4 +- Base/usr/share/man/man1/allocate.md | 4 +- Base/usr/share/man/man1/aplay.md | 6 +- Base/usr/share/man/man1/arp.md | 10 +- Base/usr/share/man/man1/asctl.md | 13 +- Base/usr/share/man/man1/base64.md | 4 +- Base/usr/share/man/man1/basename.md | 4 +- Base/usr/share/man/man1/beep.md | 6 +- Base/usr/share/man/man1/bt.md | 12 +- Base/usr/share/man/man1/cal.md | 8 +- Base/usr/share/man/man1/cat.md | 9 +- Base/usr/share/man/man1/checksum.md | 8 +- Base/usr/share/man/man1/chgrp.md | 6 +- Base/usr/share/man/man1/chmod.md | 6 +- Base/usr/share/man/man1/chown.md | 10 +- Base/usr/share/man/man1/chres.md | 4 +- Base/usr/share/man/man1/cmp.md | 19 +- Base/usr/share/man/man1/comm.md | 21 +- Base/usr/share/man/man1/config.md | 10 +- Base/usr/share/man/man1/copy.md | 7 +- Base/usr/share/man/man1/cp.md | 9 +- Base/usr/share/man/man1/crash.md | 43 +- Base/usr/share/man/man1/cut.md | 19 +- Base/usr/share/man/man1/date.md | 15 +- Base/usr/share/man/man1/dd.md | 22 +- Base/usr/share/man/man1/diff.md | 6 +- Base/usr/share/man/man1/dirname.md | 5 +- Base/usr/share/man/man1/drain.md | 4 +- Base/usr/share/man/man1/du.md | 30 +- Base/usr/share/man/man1/echo.md | 4 +- Base/usr/share/man/man1/elfdeps.md | 12 +- Base/usr/share/man/man1/env.md | 8 +- Base/usr/share/man/man1/expr.md | 49 +- Base/usr/share/man/man1/file.md | 9 +- Base/usr/share/man/man1/find.md | 169 ++--- Base/usr/share/man/man1/fortune.md | 4 +- Base/usr/share/man/man1/gml-format.md | 5 +- Base/usr/share/man/man1/grep.md | 34 +- Base/usr/share/man/man1/groups.md | 7 +- Base/usr/share/man/man1/gzip.md | 11 +- Base/usr/share/man/man1/head.md | 18 +- Base/usr/share/man/man1/id.md | 14 +- Base/usr/share/man/man1/ifconfig.md | 11 +- Base/usr/share/man/man1/js.md | 24 +- Base/usr/share/man/man1/json.md | 10 +- Base/usr/share/man/man1/keymap.md | 7 +- Base/usr/share/man/man1/less.md | 48 +- Base/usr/share/man/man1/listdir.md | 13 +- Base/usr/share/man/man1/ls.md | 51 +- Base/usr/share/man/man1/lsof.md | 15 +- Base/usr/share/man/man1/man.md | 12 +- Base/usr/share/man/man1/md.md | 5 +- Base/usr/share/man/man1/memstat.md | 2 +- Base/usr/share/man/man1/mkdir.md | 12 +- Base/usr/share/man/man1/mktemp.md | 13 +- Base/usr/share/man/man1/more.md | 2 +- Base/usr/share/man/man1/mv.md | 9 +- Base/usr/share/man/man1/nc.md | 20 +- Base/usr/share/man/man1/netstat.md | 19 +- Base/usr/share/man/man1/nl.md | 12 +- Base/usr/share/man/man1/nohup.md | 10 +- Base/usr/share/man/man1/notify.md | 6 +- Base/usr/share/man/man1/ntpquery.md | 11 +- Base/usr/share/man/man1/passwd.md | 8 +- Base/usr/share/man/man1/pgrep.md | 27 +- Base/usr/share/man/man1/pidof.md | 13 +- Base/usr/share/man/man1/pkg.md | 10 +- Base/usr/share/man/man1/pkill.md | 23 +- Base/usr/share/man/man1/pmap.md | 7 +- Base/usr/share/man/man1/pmemdump.md | 9 +- Base/usr/share/man/man1/printf.md | 36 +- Base/usr/share/man/man1/profile.md | 18 +- Base/usr/share/man/man1/ps.md | 23 +- Base/usr/share/man/man1/pwd.md | 2 +- Base/usr/share/man/man1/readelf.md | 28 +- Base/usr/share/man/man1/readlink.md | 4 +- Base/usr/share/man/man1/realpath.md | 4 +- Base/usr/share/man/man1/rev.md | 5 +- Base/usr/share/man/man1/rm.md | 11 +- Base/usr/share/man/man1/rmdir.md | 13 +- Base/usr/share/man/man1/shot.md | 12 +- Base/usr/share/man/man1/shred.md | 15 +- Base/usr/share/man/man1/shuf.md | 8 +- Base/usr/share/man/man1/sizefmt.md | 2 +- Base/usr/share/man/man1/sleep.md | 2 +- Base/usr/share/man/man1/slugify.md | 6 +- Base/usr/share/man/man1/sort.md | 13 +- Base/usr/share/man/man1/sql.md | 8 +- Base/usr/share/man/man1/stat.md | 6 +- Base/usr/share/man/man1/strace.md | 15 +- Base/usr/share/man/man1/strings.md | 10 +- Base/usr/share/man/man1/su.md | 11 +- Base/usr/share/man/man1/syscall.md | 7 +- Base/usr/share/man/man1/tail.md | 17 +- Base/usr/share/man/man1/tar.md | 22 +- Base/usr/share/man/man1/test-js.md | 20 +- Base/usr/share/man/man1/test.md | 75 +- Base/usr/share/man/man1/timezone.md | 7 +- Base/usr/share/man/man1/top.md | 6 +- Base/usr/share/man/man1/touch.md | 23 +- Base/usr/share/man/man1/tr.md | 10 +- Base/usr/share/man/man1/traceroute.md | 8 +- Base/usr/share/man/man1/tree.md | 11 +- Base/usr/share/man/man1/truncate.md | 6 +- Base/usr/share/man/man1/uname.md | 14 +- Base/usr/share/man/man1/uniq.md | 21 +- Base/usr/share/man/man1/unveil.md | 11 +- Base/usr/share/man/man1/unzip.md | 11 +- Base/usr/share/man/man1/uptime.md | 4 +- Base/usr/share/man/man1/utmpupdate.md | 13 +- Base/usr/share/man/man1/w.md | 11 +- Base/usr/share/man/man1/wallpaper.md | 6 +- Base/usr/share/man/man1/watch.md | 12 +- Base/usr/share/man/man1/watchfs.md | 23 +- Base/usr/share/man/man1/wc.md | 14 +- Base/usr/share/man/man1/which.md | 4 +- Base/usr/share/man/man1/whoami.md | 2 +- Base/usr/share/man/man1/xargs.md | 21 +- Base/usr/share/man/man1/yes.md | 5 +- Base/usr/share/man/man1/zip.md | 11 +- Base/usr/share/man/man2/accept.md | 11 +- Base/usr/share/man/man2/access.md | 15 +- Base/usr/share/man/man2/adjtime.md | 8 +- Base/usr/share/man/man2/bindmount.md | 22 +- Base/usr/share/man/man2/disown.md | 5 +- Base/usr/share/man/man2/futex.md | 130 ++-- Base/usr/share/man/man2/get_process_name.md | 8 +- Base/usr/share/man/man2/geteuid.md | 12 +- Base/usr/share/man/man2/getpid.md | 4 +- Base/usr/share/man/man2/getppid.md | 4 +- Base/usr/share/man/man2/getresuid.md | 14 +- Base/usr/share/man/man2/gettid.md | 4 +- Base/usr/share/man/man2/getuid.md | 12 +- Base/usr/share/man/man2/mkdir.md | 4 +- Base/usr/share/man/man2/mount.md | 54 +- Base/usr/share/man/man2/pipe.md | 4 +- Base/usr/share/man/man2/pledge.md | 68 +- Base/usr/share/man/man2/readlink.md | 2 +- Base/usr/share/man/man2/recvfd.md | 16 +- Base/usr/share/man/man2/remount.md | 22 +- .../man/man2/scheduler_set_parameters.md | 22 +- Base/usr/share/man/man2/sendfd.md | 14 +- Base/usr/share/man/man2/set_process_name.md | 8 +- Base/usr/share/man/man2/seteuid.md | 16 +- Base/usr/share/man/man2/setresuid.md | 14 +- Base/usr/share/man/man2/setuid.md | 16 +- Base/usr/share/man/man2/uname.md | 4 +- Base/usr/share/man/man2/unveil.md | 28 +- Base/usr/share/man/man3/basename.md | 2 +- Base/usr/share/man/man3/dirname.md | 2 +- Base/usr/share/man/man3/getopt.md | 8 +- Base/usr/share/man/man3/isatty.md | 6 +- Base/usr/share/man/man3/posix_openpt.md | 14 +- Base/usr/share/man/man3/posix_spawn.md | 8 +- .../man/man3/posix_spawn_file_actions_init.md | 2 +- .../share/man/man3/posix_spawnattr_init.md | 19 +- Base/usr/share/man/man3/utimensat.md | 34 +- Base/usr/share/man/man4/audio.md | 12 +- Base/usr/share/man/man4/full.md | 7 +- Base/usr/share/man/man4/ipc.md | 11 +- Base/usr/share/man/man4/mem.md | 7 +- Base/usr/share/man/man4/null.md | 7 +- Base/usr/share/man/man4/zero.md | 7 +- Base/usr/share/man/man5/GML/CoreObject.md | 8 +- Base/usr/share/man/man5/GML/UI-Dimensions.md | 13 +- Base/usr/share/man/man5/GML/Widget.md | 1 - .../usr/share/man/man5/GML/Widget/CheckBox.md | 5 +- .../share/man/man5/GML/Widget/ColorInput.md | 2 +- .../usr/share/man/man5/GML/Widget/ComboBox.md | 2 +- .../man5/GML/Widget/DynamicWidgetContainer.md | 25 +- Base/usr/share/man/man5/GML/Widget/Frame.md | 2 +- .../usr/share/man/man5/GML/Widget/GroupBox.md | 2 +- .../share/man/man5/GML/Widget/ImageWidget.md | 2 +- Base/usr/share/man/man5/GML/Widget/Label.md | 8 +- .../share/man/man5/GML/Widget/NumericInput.md | 10 +- .../share/man/man5/GML/Widget/Progressbar.md | 2 +- .../GML/Widget/ScrollableContainerWidget.md | 2 +- Base/usr/share/man/man5/GML/Widget/Slider.md | 2 +- Base/usr/share/man/man5/GML/Widget/SpinBox.md | 8 +- .../share/man/man5/GML/Widget/Statusbar.md | 2 +- .../share/man/man5/GML/Widget/TabWidget.md | 4 +- .../share/man/man5/GML/Widget/TextEditor.md | 2 +- Base/usr/share/man/man5/GML/Widget/Toolbar.md | 2 +- Base/usr/share/man/man5/Network.md | 13 +- Base/usr/share/man/man5/Shell.md | 215 ++++-- Base/usr/share/man/man5/SystemServer.md | 43 +- Base/usr/share/man/man5/af.md | 10 +- Base/usr/share/man/man5/clipboard.md | 14 +- Base/usr/share/man/man5/font.md | 32 +- Base/usr/share/man/man5/getopt.md | 6 +- Base/usr/share/man/man5/installed.md | 9 +- Base/usr/share/man/man5/ipc.md | 8 +- Base/usr/share/man/man5/postcreate.md | 10 +- Base/usr/share/man/man5/pp.md | 32 +- Base/usr/share/man/man6/2048.md | 8 +- Base/usr/share/man/man6/BrickGame.md | 7 +- Base/usr/share/man/man6/Chess.md | 2 +- Base/usr/share/man/man6/GameOfLife.md | 6 +- Base/usr/share/man/man6/Snake.md | 1 + Base/usr/share/man/man6/Solitaire.md | 11 +- Base/usr/share/man/man6/Spider.md | 11 +- Base/usr/share/man/man7/Audio-subsystem.md | 22 +- Base/usr/share/man/man7/Help-index.md | 7 +- Base/usr/share/man/man7/KeyboardShortcuts.md | 25 +- Base/usr/share/man/man7/Mitigations.md | 27 +- Base/usr/share/man/man7/Shell-vars.md | 39 +- Base/usr/share/man/man7/SystemServer.md | 12 +- Base/usr/share/man/man7/Tips-and-Tricks.md | 69 +- Base/usr/share/man/man7/boot_parameters.md | 117 ++- Base/usr/share/man/man7/proc.md | 28 +- Base/usr/share/man/man7/setuid_overview.md | 20 +- Base/usr/share/man/man7/sys.md | 63 +- Base/usr/share/man/man8/EchoServer.md | 2 +- Base/usr/share/man/man8/TelnetServer.md | 9 +- Base/usr/share/man/man8/WebServer.md | 14 +- Base/usr/share/man/man8/blockdev.md | 4 +- Base/usr/share/man/man8/groupadd.md | 13 +- Base/usr/share/man/man8/groupdel.md | 17 +- Base/usr/share/man/man8/lsblk.md | 2 +- Base/usr/share/man/man8/lsdev.md | 4 +- Base/usr/share/man/man8/lspci.md | 8 +- Base/usr/share/man/man8/mount.md | 12 +- Base/usr/share/man/man8/ping.md | 22 +- Base/usr/share/man/man8/pls.md | 3 +- Base/usr/share/man/man8/purge.md | 4 +- Base/usr/share/man/man8/sysctl.md | 10 +- Base/usr/share/man/man8/umount.md | 5 +- Base/usr/share/man/man8/useradd.md | 33 +- Base/usr/share/man/man8/userdel.md | 19 +- Base/usr/share/man/man8/usermod.md | 33 +- CONTRIBUTING.md | 111 +-- Documentation/AdvancedBuildInstructions.md | 100 +-- Documentation/AsynchronousDesign.md | 8 +- Documentation/BareMetalInstallation.md | 3 +- Documentation/Browser/AddNewIDLFile.md | 3 + .../Browser/BrowsingContextsAndNavigables.md | 64 +- Documentation/Browser/CSSGeneratedFiles.md | 72 +- .../Browser/LibWebFromLoadingToPainting.md | 51 +- Documentation/Browser/ProcessArchitecture.md | 4 +- Documentation/BuildInstructions.md | 19 +- Documentation/BuildInstructionsLadybird.md | 18 +- Documentation/BuildInstructionsMacOS.md | 1 + Documentation/BuildInstructionsOther.md | 3 + Documentation/BuildInstructionsWindows.md | 7 +- Documentation/BuildProfilingInstructions.md | 2 + Documentation/CLionConfiguration.md | 29 +- Documentation/CodingStyle.md | 27 +- Documentation/EmacsConfiguration.md | 28 +- Documentation/FAQ.md | 6 +- Documentation/HardwareCompatibility.md | 42 +- Documentation/HelixConfiguration.md | 11 +- Documentation/HighDPI.md | 157 ++-- .../HumanInterfaceGuidelines/Text.md | 65 +- Documentation/Kernel/AHCILocking.md | 3 +- Documentation/Kernel/Containers.md | 16 +- Documentation/Kernel/DevelopmentGuidelines.md | 40 +- Documentation/Kernel/GraphicsSubsystem.md | 73 +- Documentation/Kernel/IOWindow.md | 12 +- Documentation/Kernel/ProcFSIndexing.md | 40 +- Documentation/Kernel/RAMFS.md | 2 +- Documentation/NvimConfiguration.md | 19 +- Documentation/Patterns.md | 28 +- Documentation/QtCreatorConfiguration.md | 60 +- Documentation/README.md | 112 +-- Documentation/SelfHostedRunners.md | 38 +- Documentation/SmartPointers.md | 17 +- Documentation/SpiceIntegration.md | 9 +- Documentation/StringFormatting.md | 64 +- Documentation/TransferringFiles.md | 43 +- Documentation/Troubleshooting.md | 13 +- Documentation/VMware.md | 10 +- Documentation/VSCodeConfiguration.md | 90 +-- Documentation/VirtualBox.md | 32 +- Documentation/WritingManPages.md | 18 + Ladybird/README.md | 24 +- Meta/Lagom/Fuzzers/FuzzilliJsInstructions.md | 4 +- Meta/Lagom/ReadMe.md | 63 +- Meta/Websites/man.serenityos.org/index.md | 16 +- Meta/gn/README.md | 6 +- Ports/AvailablePorts.md | 696 +++++++++--------- Ports/README.md | 78 +- Ports/openssh/ReadMe.md | 15 +- README.md | 168 ++--- .../Libraries/LibTest/Randomized/README.md | 81 +- 310 files changed, 3571 insertions(+), 3215 deletions(-) diff --git a/Base/usr/share/man/man1/Applications.md b/Base/usr/share/man/man1/Applications.md index 00dfe93c1f9..c0f66b6e26c 100644 --- a/Base/usr/share/man/man1/Applications.md +++ b/Base/usr/share/man/man1/Applications.md @@ -6,37 +6,37 @@ Applications - SerenityOS GUI applications SerenityOS comes with a suite of GUI applications. The applications are divided into multiple categories, through which they are available in the System Menu. -Note that many applications can be disabled at SerenityOS build time if desired. Therefore, depending on your SerenityOS build configuration, not all applications will be available. +Note that many applications can be disabled at SerenityOS build time if desired. Therefore, depending on your SerenityOS build configuration, not all applications will be available. ## See also -- Documentation for SerenityOS Games in section 6 +- Documentation for SerenityOS Games in section 6 ### List of Application manpages -- [3D File Viewer](help://man/1/Applications/3DFileViewer) -- [About](help://man/1/Applications/About) -- [Analog Clock](help://man/1/Applications/AnalogClock) -- [Assistant](help://man/1/Applications/Assistant) -- [Browser](help://man/1/Applications/Browser) -- [Calculator](help://man/1/Applications/Calculator) -- [Calendar](help://man/1/Applications/Calendar) -- [CatDog](help://man/1/Applications/CatDog) -- [Certificate Settings](help://man/1/Applications/CertificateSettings) -- [Character Map](help://man/1/Applications/CharacterMap) -- [Eyes](help://man/1/Applications/Eyes) -- [FontEditor](help://man/1/Applications/FontEditor) -- [GML Playground](help://man/1/Applications/GMLPlayground) -- [Help](help://man/1/Applications/Help) -- [Hex Editor](help://man/1/Applications/HexEditor) -- [Image Viewer](help://man/1/Applications/ImageViewer) -- [Magnifier](help://man/1/Applications/Magnifier) -- [Mail](help://man/1/Applications/Mail) -- [Maps](help://man/1/Applications/Maps) -- [Mouse Settings](help://man/1/Applications/MouseSettings) -- [Pixel Paint](help://man/1/Applications/PixelPaint) -- [Presenter](help://man/1/Applications/Presenter) -- [Profiler](help://man/1/Applications/Profiler) -- [SQL Studio](help://man/1/Applications/SQLStudio) -- [Terminal](help://man/1/Applications/Terminal) -- [Text Editor](help://man/1/Applications/TextEditor) +- [3D File Viewer](help://man/1/Applications/3DFileViewer) +- [About](help://man/1/Applications/About) +- [Analog Clock](help://man/1/Applications/AnalogClock) +- [Assistant](help://man/1/Applications/Assistant) +- [Browser](help://man/1/Applications/Browser) +- [Calculator](help://man/1/Applications/Calculator) +- [Calendar](help://man/1/Applications/Calendar) +- [CatDog](help://man/1/Applications/CatDog) +- [Certificate Settings](help://man/1/Applications/CertificateSettings) +- [Character Map](help://man/1/Applications/CharacterMap) +- [Eyes](help://man/1/Applications/Eyes) +- [FontEditor](help://man/1/Applications/FontEditor) +- [GML Playground](help://man/1/Applications/GMLPlayground) +- [Help](help://man/1/Applications/Help) +- [Hex Editor](help://man/1/Applications/HexEditor) +- [Image Viewer](help://man/1/Applications/ImageViewer) +- [Magnifier](help://man/1/Applications/Magnifier) +- [Mail](help://man/1/Applications/Mail) +- [Maps](help://man/1/Applications/Maps) +- [Mouse Settings](help://man/1/Applications/MouseSettings) +- [Pixel Paint](help://man/1/Applications/PixelPaint) +- [Presenter](help://man/1/Applications/Presenter) +- [Profiler](help://man/1/Applications/Profiler) +- [SQL Studio](help://man/1/Applications/SQLStudio) +- [Terminal](help://man/1/Applications/Terminal) +- [Text Editor](help://man/1/Applications/TextEditor) diff --git a/Base/usr/share/man/man1/Applications/3DFileViewer.md b/Base/usr/share/man/man1/Applications/3DFileViewer.md index 0051e68954e..4322be87986 100644 --- a/Base/usr/share/man/man1/Applications/3DFileViewer.md +++ b/Base/usr/share/man/man1/Applications/3DFileViewer.md @@ -18,33 +18,33 @@ It currently supports opening the [Wavefront OBJ file format](https://en.wikiped ## Features -By default, 3D File Viewer opens with a rotating [Utah teapot](https://en.wikipedia.org/wiki/Utah_teapot), a standard 3D test model. Open files via *File → Open* (`Ctrl+O`) or dragging and dropping files into the application. Sample files can be found in `Documents/3D Models`. +By default, 3D File Viewer opens with a rotating [Utah teapot](https://en.wikipedia.org/wiki/Utah_teapot), a standard 3D test model. Open files via _File → Open_ (`Ctrl+O`) or dragging and dropping files into the application. Sample files can be found in `Documents/3D Models`. Orbit around the model by grabbing it with the cursor, and zoom in and out with the mouse wheel. ### View Options -* View in Fullscreen mode by pressing `F11` and press `Esc` to return to windowed mode. -* **Rotation Axis** - Enable or disable rotation: - * **X** rotates upwards. - * **Y** rotates right. - * **Z** rotates clockwise. -* **Rotation Speed** - Set to slow, normal, fast or disable. -* **Show Frame Rate** - Display FPS (frames per second) and frame time values (indicating how long it took to render a single frame) in the top-right corner. +- View in Fullscreen mode by pressing `F11` and press `Esc` to return to windowed mode. +- **Rotation Axis** - Enable or disable rotation: + - **X** rotates upwards. + - **Y** rotates right. + - **Z** rotates clockwise. +- **Rotation Speed** - Set to slow, normal, fast or disable. +- **Show Frame Rate** - Display FPS (frames per second) and frame time values (indicating how long it took to render a single frame) in the top-right corner. ### Texture Options To load a texture, ensure there's a [Bitmap image file](https://en.wikipedia.org/wiki/BMP_file_format) (`.bmp`) with the same name as the OBJ file in the same folder and 3D File Viewer will attempt to load it automatically. -* **Enable Texture** - On by default, disable for a blank (gray) model. -* **Wrap S or T** - Controls how a texture is applied horizontally (S) or vertically (T): - * **Repeat** - Tiles the texture along the axis. - * **Mirrored** - Tiles and mirrors the texture along the axis. - * **Clamp** - Stretches or clamps the texture edges instead of repeating it. -* **Scale** - Adjusts texture size (e.g. `0.5` reduces by half, `2x` doubles the size). -* **Mag Filter** - Determines the appearance of textures when enlarged beyond their original resolution. - * **Nearest** - *Nearest Neighbor* means no scaling is applied to the texture, resulting in a pixellated look. - * **Linear** - *Linear Interpolation* scales the image by estimating pixel values, resulting in a smoother image. +- **Enable Texture** - On by default, disable for a blank (gray) model. +- **Wrap S or T** - Controls how a texture is applied horizontally (S) or vertically (T): + - **Repeat** - Tiles the texture along the axis. + - **Mirrored** - Tiles and mirrors the texture along the axis. + - **Clamp** - Stretches or clamps the texture edges instead of repeating it. +- **Scale** - Adjusts texture size (e.g. `0.5` reduces by half, `2x` doubles the size). +- **Mag Filter** - Determines the appearance of textures when enlarged beyond their original resolution. + - **Nearest** - _Nearest Neighbor_ means no scaling is applied to the texture, resulting in a pixellated look. + - **Linear** - _Linear Interpolation_ scales the image by estimating pixel values, resulting in a smoother image. Currently, the flashing color lights can't be disabled. @@ -52,7 +52,7 @@ Settings persist whilst the application is open with different files, but do not ## Arguments -* `file`: The 3D file to be viewed. +- `file`: The 3D file to be viewed. ## Example diff --git a/Base/usr/share/man/man1/Applications/About.md b/Base/usr/share/man/man1/Applications/About.md index 766ba8df1b4..997a4b2588b 100644 --- a/Base/usr/share/man/man1/Applications/About.md +++ b/Base/usr/share/man/man1/Applications/About.md @@ -14,7 +14,7 @@ $ About `About` is an application that displays information about SerenityOS. -On the left is the official Ladyball logo. Designed by Katalin Kult, it combines the Yin-Yang symbol with the distinctive shell pattern of a [ladybird](https://en.wikipedia.org/wiki/Coccinellidae), the projects's insect motif. It symbolizes the SerenityOS philosophy, encompassing the *Serenity Prayer's* acceptance of the uncontrollable, the *Yin and yang* concept of balancing opposing forces, and *Lagom*, the Swedish concept of moderation or finding "just the right amount." +On the left is the official Ladyball logo. Designed by Katalin Kult, it combines the Yin-Yang symbol with the distinctive shell pattern of a [ladybird](https://en.wikipedia.org/wiki/Coccinellidae), the projects's insect motif. It symbolizes the SerenityOS philosophy, encompassing the _Serenity Prayer's_ acceptance of the uncontrollable, the _Yin and yang_ concept of balancing opposing forces, and _Lagom_, the Swedish concept of moderation or finding "just the right amount." Since there are no official releases of the project, the version number is denoted as `1.0-dev` and the revision number reflects the latest Git commit's hash. diff --git a/Base/usr/share/man/man1/Applications/Assistant.md b/Base/usr/share/man/man1/Applications/Assistant.md index 9d196a22e55..d9794167bb3 100644 --- a/Base/usr/share/man/man1/Applications/Assistant.md +++ b/Base/usr/share/man/man1/Applications/Assistant.md @@ -16,7 +16,7 @@ $ Assistant ### Features -* Enter a URL to open it in [Browser](help://man/1/Applications/Browser), e.g. `serenityos.org`. -* Perform quick calculations by typing the equal sign (=) followed by a mathematical expression, e.g. `=22*101`. Press `Return` to copy the result. -* Run commands in [Terminal](help://man/1/Applications/Terminal) by prefixing them with a dollar sign ($), e.g. `$ uname -a`. -* Launch applications with arguments, e.g. launch [Pixel Paint](help://man/1/Applications/PixelPaint) with a file: `pp image.png`. +- Enter a URL to open it in [Browser](help://man/1/Applications/Browser), e.g. `serenityos.org`. +- Perform quick calculations by typing the equal sign (=) followed by a mathematical expression, e.g. `=22*101`. Press `Return` to copy the result. +- Run commands in [Terminal](help://man/1/Applications/Terminal) by prefixing them with a dollar sign ($), e.g. `$ uname -a`. +- Launch applications with arguments, e.g. launch [Pixel Paint](help://man/1/Applications/PixelPaint) with a file: `pp image.png`. diff --git a/Base/usr/share/man/man1/Applications/Browser.md b/Base/usr/share/man/man1/Applications/Browser.md index 212917db74d..ae45d93e1d7 100644 --- a/Base/usr/share/man/man1/Applications/Browser.md +++ b/Base/usr/share/man/man1/Applications/Browser.md @@ -16,12 +16,12 @@ Browser is an application used to view the World Wide Web. It is built on top of ## Options -* `--help`: Display help message and exit -* `--version`: Display version number and exit +- `--help`: Display help message and exit +- `--version`: Display version number and exit ## Arguments -* `urls`: A list of urls to open, one per tab. If none are specified, then the homepage will be opened instead. +- `urls`: A list of urls to open, one per tab. If none are specified, then the homepage will be opened instead. ## Examples diff --git a/Base/usr/share/man/man1/Applications/CatDog.md b/Base/usr/share/man/man1/Applications/CatDog.md index 1cbf05698a1..e8d139c9d0b 100644 --- a/Base/usr/share/man/man1/Applications/CatDog.md +++ b/Base/usr/share/man/man1/Applications/CatDog.md @@ -14,7 +14,7 @@ $ CatDog `CatDog` is an animated screenmate application in the form of a virtual pet. -It was inspired by [Neko](https://en.wikipedia.org/wiki/Neko_(software)). The name derives from its ambiguous appearance: is it a cat, a dog, or a hybrid? +It was inspired by [Neko](). The name derives from its ambiguous appearance: is it a cat, a dog, or a hybrid? Its helpful suggestions evoke the animated assistants popular at the turn of the millennium, such as [Clippy](https://en.wikipedia.org/wiki/Office_Assistant). @@ -28,10 +28,10 @@ Additionally, CatDog offers helpful suggestions depending on the currently activ CatDog has multiple states: -- *Sleeping* if the mouse cursor hasn’t moved in some time -- *Alert* if woken by the mouse cursor or speaking after being idle -- *Dressed as an Artist* if [Pixel Paint](help://man/1/Applications/PixelPaint) or [Font Editor](help://man/1/Applications/FontEditor) are open -- *Dressed as an Inspector* if [Profiler](help://man/1/Applications/Profiler) or System Monitor are open +- _Sleeping_ if the mouse cursor hasn’t moved in some time +- _Alert_ if woken by the mouse cursor or speaking after being idle +- _Dressed as an Artist_ if [Pixel Paint](help://man/1/Applications/PixelPaint) or [Font Editor](help://man/1/Applications/FontEditor) are open +- _Dressed as an Inspector_ if [Profiler](help://man/1/Applications/Profiler) or System Monitor are open To exit, right-click on CatDog and select `Quit` or, if active, press `Alt+F4`. diff --git a/Base/usr/share/man/man1/Applications/CertificateSettings.md b/Base/usr/share/man/man1/Applications/CertificateSettings.md index 38be3ab8c03..4b5d39f7a63 100644 --- a/Base/usr/share/man/man1/Applications/CertificateSettings.md +++ b/Base/usr/share/man/man1/Applications/CertificateSettings.md @@ -11,12 +11,13 @@ $ CertificateSettings ``` ## Description + `Certificate Settings` is an application for managing digital certificates in SerenityOS. Certificates are used for establishing a user's credentials when trying to create secure connection between a client and server by matching a public and private key. -The *Certificate Store* lists all of the certificates currently stored in the system, the Trusted Root Certification Authorities (CAs) they were issued by and their expiration dates. +The _Certificate Store_ lists all of the certificates currently stored in the system, the Trusted Root Certification Authorities (CAs) they were issued by and their expiration dates. ### Features -Import and export CAs as Privacy-Enhanced Mail files (`.pem`). \ No newline at end of file +Import and export CAs as Privacy-Enhanced Mail files (`.pem`). diff --git a/Base/usr/share/man/man1/Applications/CharacterMap.md b/Base/usr/share/man/man1/Applications/CharacterMap.md index c5593c2884f..af11aa97491 100644 --- a/Base/usr/share/man/man1/Applications/CharacterMap.md +++ b/Base/usr/share/man/man1/Applications/CharacterMap.md @@ -18,15 +18,17 @@ Character Map is a GUI application for viewing, searching for, and copying Unico ## Examples To open Character Map: + ```sh $ CharacterMap ``` To view a list of all characters that have "yak" in their name: + ```sh $ CharacterMap --search "yak" ``` ## See Also -* [`FontEditor`(1)](help://man/1/Applications/FontEditor) To edit the fonts instead of just viewing them. +- [`FontEditor`(1)](help://man/1/Applications/FontEditor) To edit the fonts instead of just viewing them. diff --git a/Base/usr/share/man/man1/Applications/Eyes.md b/Base/usr/share/man/man1/Applications/Eyes.md index 014145c1265..0f379b458f7 100644 --- a/Base/usr/share/man/man1/Applications/Eyes.md +++ b/Base/usr/share/man/man1/Applications/Eyes.md @@ -12,10 +12,10 @@ $ Eyes [--num-eyes number] [--max-in-row number] [--grid-rows number] [--grid-co ## Options -* `--help`: Display help message and exit -* `--version`: Print version -* `-n number`, `--num-eyes number`: Number of eyes -* `-m number`, `--max-in-row number`: Maximum number of eyes in a row -* `-r number`, `--grid-rows number`: Number of rows in grid (incompatible with --number) -* `-c number`, `--grid-cols number`: Number of columns in grid (incompatible with --number) -* `-h`, `--hide-window`: Hide window frame +- `--help`: Display help message and exit +- `--version`: Print version +- `-n number`, `--num-eyes number`: Number of eyes +- `-m number`, `--max-in-row number`: Maximum number of eyes in a row +- `-r number`, `--grid-rows number`: Number of rows in grid (incompatible with --number) +- `-c number`, `--grid-cols number`: Number of columns in grid (incompatible with --number) +- `-h`, `--hide-window`: Hide window frame diff --git a/Base/usr/share/man/man1/Applications/FontEditor.md b/Base/usr/share/man/man1/Applications/FontEditor.md index 2350d2c8ac9..a1ed7580311 100644 --- a/Base/usr/share/man/man1/Applications/FontEditor.md +++ b/Base/usr/share/man/man1/Applications/FontEditor.md @@ -17,7 +17,9 @@ FontEditor is the font editing application for creating and editing bitmap font ![](FontEditor.png) ### Basic Parts + FontEditor has the following basic parts: + 1. The menu bar at the top 2. The toolbar 3. The main workspace @@ -26,80 +28,95 @@ FontEditor has the following basic parts: Presently, you can resize the entire FontEditor form to your liking. You can turn the visibility of Font Metadata and Unicode Blocks on or off. You can change the glyph editor window zoom factor. All of these things are currently available in FontEditor automatically. ### The Toolbar + The Toolbar contains the same functional entries as that of the Menubar and is represented as clickable icons. Hovering on each icon will display additional information listed in the status bar which further states what each icon does. ### The Main Workspace + The main workspace has three partitions: -- The ***left section*** contains the glyph editor window. This window has three different zoom factors for ease of use and for your viewing comfort. They are 500%, 1000% and 1500%. You can freely switch to any zoom level at anytime while creating your font. Don't let the size of the glyph editor window fool you. This is where you will spend about 95% of the time. And the task is that of shaping each glyph by left-clicking on the mouse. You can form a dot, a line, or a complete glyph just by connecting the dots. If you need to undo a certain location with a black dot, you can right-click on top of the target area and it will revert back to empty. Each grid area can hold any of the three states: 1) on or black 2) off or white 3) empty or gray. On state is displayed as black by default. Off state is displayed as white by default. Empty state is displayed as gray by default. Off state or white is relevant most specially if the font is fixed-width as it dictates the distance a glyph will have from left, center or right. Empty state or gray is important for variable-width font as it affects the overall width of the glyph. For variable width fonts, you move the glyph flushed left on the glyph editor window and remove any extra empty grids by decrementing the present column counter located right under the glyph editor window and thereby leaving only the entire glyph all by itself. Below the glyph editor is the glyph tool which contains the following: the pen icon for creating the glyph itself, the move icon to enable the entire glyph move to top, down, left or right from within the glyph editor window. Below the glyph tool are the transform icons which are flip horizontal, flip vertical, rotate counter-clockwise 90°and rotate clockwise 90°. Transform tools are most helpful when copying over existing glyphs and transforming them to form a new glyph. A becomes V, M becomes W, c becomes e, n becomes u, etc. +- The **_left section_** contains the glyph editor window. This window has three different zoom factors for ease of use and for your viewing comfort. They are 500%, 1000% and 1500%. You can freely switch to any zoom level at anytime while creating your font. Don't let the size of the glyph editor window fool you. This is where you will spend about 95% of the time. And the task is that of shaping each glyph by left-clicking on the mouse. You can form a dot, a line, or a complete glyph just by connecting the dots. If you need to undo a certain location with a black dot, you can right-click on top of the target area and it will revert back to empty. Each grid area can hold any of the three states: 1) on or black 2) off or white 3) empty or gray. On state is displayed as black by default. Off state is displayed as white by default. Empty state is displayed as gray by default. Off state or white is relevant most specially if the font is fixed-width as it dictates the distance a glyph will have from left, center or right. Empty state or gray is important for variable-width font as it affects the overall width of the glyph. For variable width fonts, you move the glyph flushed left on the glyph editor window and remove any extra empty grids by decrementing the present column counter located right under the glyph editor window and thereby leaving only the entire glyph all by itself. Below the glyph editor is the glyph tool which contains the following: the pen icon for creating the glyph itself, the move icon to enable the entire glyph move to top, down, left or right from within the glyph editor window. Below the glyph tool are the transform icons which are flip horizontal, flip vertical, rotate counter-clockwise 90°and rotate clockwise 90°. Transform tools are most helpful when copying over existing glyphs and transforming them to form a new glyph. A becomes V, M becomes W, c becomes e, n becomes u, etc. -- The ***middle section*** contains two parts: the upper part which holds the entire glyph content of the font, or lack thereof if you are making a new one. And the lower part which contains ***Metadata*** information such as name, family, weight, slope, presentation size, mean line, baseline, glyph spacing and if the font is either fixed-width or variable-width. You can still further tweak your font parameters via the Metadata section. The `Fixed width` toggle located at the right side next to Glyph spacing is of special note. It applies to the entire font file. It does not only apply to a single glyph or group of glyphs. It is the differentiating factor that informs the system if the font is or is not fixed-width. Fixed-width fonts are mostly used for Terminals and for displaying source code. +- The **_middle section_** contains two parts: the upper part which holds the entire glyph content of the font, or lack thereof if you are making a new one. And the lower part which contains **_Metadata_** information such as name, family, weight, slope, presentation size, mean line, baseline, glyph spacing and if the font is either fixed-width or variable-width. You can still further tweak your font parameters via the Metadata section. The `Fixed width` toggle located at the right side next to Glyph spacing is of special note. It applies to the entire font file. It does not only apply to a single glyph or group of glyphs. It is the differentiating factor that informs the system if the font is or is not fixed-width. Fixed-width fonts are mostly used for Terminals and for displaying source code. -- The ***right section*** displays a searchable list of Unicode Blocks. -Metadata and Unicode Blocks can be turned on or off in `Menu → View`. Selecting a Unicode Block will show only the glyphs contained within the range of that block. Basic Latin covers 000-007F, Latin-1 Supplement covers 0080-00FF, Latin Extended-A covers 0100-017F and so on and so forth. Global search for a glyph is affected when a certain block is currently selected. Only by selecting `Show All` will the global glyph search work as expected. So make it a habit of confirming that Show All is active before searching for a glyph. +- The **_right section_** displays a searchable list of Unicode Blocks. + Metadata and Unicode Blocks can be turned on or off in `Menu → View`. Selecting a Unicode Block will show only the glyphs contained within the range of that block. Basic Latin covers 000-007F, Latin-1 Supplement covers 0080-00FF, Latin Extended-A covers 0100-017F and so on and so forth. Global search for a glyph is affected when a certain block is currently selected. Only by selecting `Show All` will the global glyph search work as expected. So make it a habit of confirming that Show All is active before searching for a glyph. ### The status bar + The status bar displays additional information describing what each menu entry and toolbar icon does. It identifies the unicode value of the glyph currently under the cursor. It shows the glyph's visual representation (if available), description and dimensions. The right-most segment displays the code point range of the currently selected Unicode Block. Clicking this segment will toggle the display of the Unicode Block list. Second only to the glyph editor window, the status bar is your next best friend on your path to becoming a font master. ## Tutorial: Create a new font + ![](FontEditor_New_Font.png) To create a new font, you can either click on New Font icon on the Toolbar or go to `File → New Font` in the Menubar. A wizard will walk you through setting the needed parameters for your new font. ### Typeface Properties + ![](FontEditor_Typeface_properties.png) You can try out the default values just to get the feel of the program. ### Glyph Properties + ![](FontEditor_Glyph_properties.png) Just click **Finish** when you are so inclined. ### Edit Glyph Properties + ![](FontEditor_Edit_Glyph_properties.png) Adjust the values to suit your needs. The higher the value, the larger the font size. ### Untitled font + ![](FontEditor_Untitled.png) Congratulations on your successful initial font setup. Now you are ready to begin. And begin you shall. There is more to font creation than simply scribbling away. You need to always remind yourself this question: "Where is the fun in that?". Start with what you need to do while striving to achieve fun in the process. Let's be honest, font creation is one of the many thankless jobs, unless and until there is fun in it, why bother? ### Launch another instance + ![](FontEditor_Launching_second_instance.png) The figure above shows where you can find FontEditor from inside the SerenityOS desktop. ### Side by side + ![](FontEditor_Twins_sidebyside.png) Having another instance of FontEditor can help boost productivity. This is most noticeable when one is just starting out in using FontEditor and trying out how to best make use of the application. Don't be afraid to experiment, let your inner font master slowly shine through. It is best to maintain the feeling of having fun while silently grinning from ear to ear as you steadily create form and personality in your font. Don't be afraid to start again, if you must. As with the entire workflow, being aware when to start, when to stop and when to reset is crucial. With FontEditor to assist you, starting from scratch is no longer an arduous process. ### Save font + ![](FontEditor_Save_font_as.png) Save your font by following the recommended `FontName + FontStyle + FontPresentationSize + .font` naming convention. ### Continue Editing + ![](FontEditor_Continue_editing_current_font.png) The figure above shows some previously made glyphs. Those with sharp eyes can immediately see that the glyphs for M and W, O and Q came from the same base. W was copied over from M and was flipped horizontally. Q was copied over from O and a descender was added to achieve the final glyph. Continue editing your font by adding more glyphs into it. Take your time in creating the font, only you know the reason why the glyph is formed the way it is. You know why the height and the width is so, why the curvature is just so. Aside from achieving balance, maintain the spirit of fun in making your font. The more glyphs are added, the easier it is to get the general feel and character of the font. Remember to always save and to save often. ### fonts.serenityos.net + ![](Fonts_SerenityOS_dot_Net.png) It is highly recommended to use our own [fonts portal](https://fonts.serenityos.net) as one of your primary resource for glyph and font information. The others are [Unicode charts [unicode.org]](https://www.unicode.org/charts/) and our [wiki](https://wiki.serenityos.net). ### Search glyph + ![](Fonts_SerenityOS_dot_Net_search_result.png) Figure above depicts a search session on the [fonts.serenityos.net](https://fonts.serenityos.net) portal. ### Search detail + ![](Fonts_SerenityOS_dot_Net_result_detail.png) The same search session displaying result of the previous query. -So there you have it, by now you have at least an idea of how to make ***SerenityOS*** fonts using **FontEditor**. For any font-related questions or inquiries, just drop by the official [SerenityOS Discord #fonts](https://discord.com/channels/830522505605283862/927893781968191508). +So there you have it, by now you have at least an idea of how to make **_SerenityOS_** fonts using **FontEditor**. For any font-related questions or inquiries, just drop by the official [SerenityOS Discord #fonts](https://discord.com/channels/830522505605283862/927893781968191508). diff --git a/Base/usr/share/man/man1/Applications/GMLPlayground.md b/Base/usr/share/man/man1/Applications/GMLPlayground.md index ba8310e2a9c..dc112230f09 100644 --- a/Base/usr/share/man/man1/Applications/GMLPlayground.md +++ b/Base/usr/share/man/man1/Applications/GMLPlayground.md @@ -12,7 +12,7 @@ $ GMLPlayground [file] ## Arguments -* `file`: Path of GML file to load +- `file`: Path of GML file to load ## Description @@ -31,5 +31,4 @@ $ GMLPlayground /home/anon/example.gml ## See also -* [`gml-format`(1)](help://man/1/gml-format) For automated GML formatting - +- [`gml-format`(1)](help://man/1/gml-format) For automated GML formatting diff --git a/Base/usr/share/man/man1/Applications/Help.md b/Base/usr/share/man/man1/Applications/Help.md index ef51e22699c..d12802b00d3 100644 --- a/Base/usr/share/man/man1/Applications/Help.md +++ b/Base/usr/share/man/man1/Applications/Help.md @@ -21,20 +21,25 @@ It lets you search for and read manual pages (or "man pages"). ## Examples To open Help: + ```sh $ Help ``` To open documentation for the `echo` command: + ```sh $ Help echo ``` To open the documentation for the `mkdir` command: + ```sh $ Help 1 mkdir ``` + Conversely, to open the documentation about the `mkdir()` syscall: + ```sh $ Help 2 mkdir ``` @@ -46,5 +51,5 @@ this man page should be located at `/usr/share/man/man1/Applications/Help.md`. ## See Also -* [`man`(1)](help://man/1/man) To read these same man pages from the terminal -* [`man`(7)](help://man/7/man) For an overview on how manpages are organized +- [`man`(1)](help://man/1/man) To read these same man pages from the terminal +- [`man`(7)](help://man/7/man) For an overview on how manpages are organized diff --git a/Base/usr/share/man/man1/Applications/HexEditor.md b/Base/usr/share/man/man1/Applications/HexEditor.md index fee593bb34e..b64ca64e309 100644 --- a/Base/usr/share/man/man1/Applications/HexEditor.md +++ b/Base/usr/share/man/man1/Applications/HexEditor.md @@ -23,22 +23,23 @@ Hex Editor abstracts data access into documents, one for memory based streaming The core feature of Hex Editor is value inspector functionality. The inspector operates on current cursor position (or selection start range if one is selected) and interprets bytes moving forward as various data types. The inspector can toggle between big and little endian modes. A value selected in the inspector has its associated bytes that makes up that value gets highlighted in the editor. ### Find value + One can search using ASCII string or Hex value, the result will be displayed on the right side with corresponding ValueInspector information. ![](HexEditor_Find_Value.png) ### Copy value -An option to copy as hex value, as text, or as C-code is available and can extract the file in parts or as a whole. The figure below shows all three output formats transferred into Text Editor. +An option to copy as hex value, as text, or as C-code is available and can extract the file in parts or as a whole. The figure below shows all three output formats transferred into Text Editor. ![](HexEditor_Copy_Hex_Text_C_Code.png) -Hex Editor's simple and straight-forward interface offers search, export, byte pattern insertions and statistics. +Hex Editor's simple and straight-forward interface offers search, export, byte pattern insertions and statistics. ## Options -* `-a`, `--annotations`: Path to an annotations file to load on startup +- `-a`, `--annotations`: Path to an annotations file to load on startup ## Arguments -* `file`: File to open on startup +- `file`: File to open on startup diff --git a/Base/usr/share/man/man1/Applications/ImageViewer.md b/Base/usr/share/man/man1/Applications/ImageViewer.md index 1b9fe87af0f..2ea67930f7a 100644 --- a/Base/usr/share/man/man1/Applications/ImageViewer.md +++ b/Base/usr/share/man/man1/Applications/ImageViewer.md @@ -14,15 +14,15 @@ $ ImageViewer [file] ImageViewer is an image viewing application for SerenityOS. -For user convenience, basic image manipulation facilities exist like image rotation clockwise or counter-clockwise, image flip horizontal or vertical, zoom in, zoom out, zoom reset, fullscreen view and fit image to view. +For user convenience, basic image manipulation facilities exist like image rotation clockwise or counter-clockwise, image flip horizontal or vertical, zoom in, zoom out, zoom reset, fullscreen view and fit image to view. -File manipulation has no effect on the image. Flip or rotate actions are not saved or committed, it is simply ignored when the application is closed. +File manipulation has no effect on the image. Flip or rotate actions are not saved or committed, it is simply ignored when the application is closed. ImageViewer is even smart enough to detect other images and display them when clicking on the navigation buttons or when using direction arrows. ImageViewer can even set the currently loaded image as a Desktop Wallpaper. ## Arguments -* `file`: The image file to be displayed. +- `file`: The image file to be displayed. ## Examples diff --git a/Base/usr/share/man/man1/Applications/Magnifier.md b/Base/usr/share/man/man1/Applications/Magnifier.md index 14b6fb26e51..c3d6e5103cc 100644 --- a/Base/usr/share/man/man1/Applications/Magnifier.md +++ b/Base/usr/share/man/man1/Applications/Magnifier.md @@ -24,4 +24,4 @@ To lock the location, making Magnifier stop following your mouse and stay in pla To view a pixel grid overlay, press `G`. -For users with slight visual impairment, Magnifier can apply several filters to the captured image. Click on the *Accessibility* menu and select one of the impairment categories available in the drop-down list. +For users with slight visual impairment, Magnifier can apply several filters to the captured image. Click on the _Accessibility_ menu and select one of the impairment categories available in the drop-down list. diff --git a/Base/usr/share/man/man1/Applications/Mail.md b/Base/usr/share/man/man1/Applications/Mail.md index 1e054b96dcf..0c617e053aa 100644 --- a/Base/usr/share/man/man1/Applications/Mail.md +++ b/Base/usr/share/man/man1/Applications/Mail.md @@ -1,6 +1,6 @@ ## Name -![Icon](/res/icons/16x16/app-mail.png) Mail - Serenity e-mail client +![Icon](/res/icons/16x16/app-mail.png) Mail - Serenity e-mail client [Open](file:///bin/Mail) @@ -19,6 +19,7 @@ See the Examples section for an example configuration file. ## Examples `~/.config/Mail.ini`: + ```ini [Connection] Server=email.example.com diff --git a/Base/usr/share/man/man1/Applications/Maps.md b/Base/usr/share/man/man1/Applications/Maps.md index f181a99fd60..fa233011529 100644 --- a/Base/usr/share/man/man1/Applications/Maps.md +++ b/Base/usr/share/man/man1/Applications/Maps.md @@ -17,16 +17,18 @@ $ Maps The default data provider is [OpenStreetMaps](https://www.openstreetmap.org/), an open-source community-maintained map similar in spirit to Wikipedia. ## Features + Pan around the map by clicking and dragging. Zoom by using the toolbar icons, the mouse wheel or `Ctrl +` to zoom-in and `Ctrl -` to zoom-out. Reset the zoom to a global view with `Ctrl 0`. Double-clicking anywhere on the map zooms-in to that location. Double-clicking whilst holding `Shift` zooms-out. Right-click on a location to: -* Copy its coordinates to the Clipboard -* Save it to your favorites -* Open it in various mapping services -* Center the map on it + +- Copy its coordinates to the Clipboard +- Save it to your favorites +- Open it in various mapping services +- Center the map on it Show and hide the search panel by clicking on the leftmost magnifying glass in the toolbar. Type your query, press `Return` and then click on a result to focus on it in the map. Navigate the search results with the `Up` and `Down` arrow keys. diff --git a/Base/usr/share/man/man1/Applications/PixelPaint.md b/Base/usr/share/man/man1/Applications/PixelPaint.md index 9fc0fafefb2..d62605567e7 100644 --- a/Base/usr/share/man/man1/Applications/PixelPaint.md +++ b/Base/usr/share/man/man1/Applications/PixelPaint.md @@ -1,15 +1,18 @@ ## Name + ![Icon](/res/icons/16x16/app-pixel-paint.png) Pixel Paint - Image Editor [Open](file:///bin/PixelPaint) ## Synopsis + ```sh $ PixelPaint [file] $ pp ``` ## Description + `Pixel Paint` is a feature-rich image editing application inspired by the likes of classic [Microsoft Paint](https://en.wikipedia.org/wiki/Microsoft_Paint#Windows_9x), though includes many more advanced features such as tabs, layers and filters. Documents can be saved as Pixel Paint Files (`.pp`), preserving layers and images. @@ -17,167 +20,211 @@ Documents can be saved as Pixel Paint Files (`.pp`), preserving layers and image The supported export formats are BMP, PNG and QOI ([Quite Okay Image Format](https://qoiformat.org)). ## User Interface + ![Pixel Paint Interface](PixelPaint.png) The interface follows familiar conventions, making it easy for users experienced with other image editors to pick up. Most options are accessible through the Menu bar and are searchable with `Ctrl+Shift+A`. ### Toolbar -The toolbar contains common actions such as creating, opening and saving a file. It also provides quick access to useful zoom levels (*Fit to width*, *Fit to height* and *Fit entire image*). + +The toolbar contains common actions such as creating, opening and saving a file. It also provides quick access to useful zoom levels (_Fit to width_, _Fit to height_ and _Fit entire image_). #### Levels + ![Levels Window](PixelPaint_Levels.png) The last icon on the toolbar opens the levels adjustment window. Levels control the exposure (light) in an image. -* **Brightness** - Lighten or darken all colors. -* **Contrast** - Increase or decrease the difference between light and dark areas. -* **Gamma** - Redistribute light intensities, allowing adjustments that can bring a digital image closer to the way human eyes perceive details, particularly in darker areas. + +- **Brightness** - Lighten or darken all colors. +- **Contrast** - Increase or decrease the difference between light and dark areas. +- **Gamma** - Redistribute light intensities, allowing adjustments that can bring a digital image closer to the way human eyes perceive details, particularly in darker areas. ### Main Workspace -* The tab bar above the canvas allows multiple documents to be open simultaneously. -* Surrounding the canvas is a vertical and horizontal ruler. When the Guide Tool is active, dragging from these rulers creates a line guide. -* In the center is the Canvas in which you can paint, create shapes, write text and manipulate images. Use the left mouse-button to paint with the primary color and the right mouse-button to paint with the secondary color. Zoom in/out with `Ctrl +` / `Ctrl -` or use the mouse wheel. Pan with the middle-mouse button. Zooming-in far enough reveals a pixel grid which is useful for precise work, such as making pixel art. + +- The tab bar above the canvas allows multiple documents to be open simultaneously. +- Surrounding the canvas is a vertical and horizontal ruler. When the Guide Tool is active, dragging from these rulers creates a line guide. +- In the center is the Canvas in which you can paint, create shapes, write text and manipulate images. Use the left mouse-button to paint with the primary color and the right mouse-button to paint with the secondary color. Zoom in/out with `Ctrl +` / `Ctrl -` or use the mouse wheel. Pan with the middle-mouse button. Zooming-in far enough reveals a pixel grid which is useful for precise work, such as making pixel art. ### Color Panel + ![Color Panel](PixelPaint_Color_Panel.png) Below the canvas is the Color Panel. On the left is the Color Picker, showing the currently selected colors. The inner color is the primary color, the outer color is the secondary color. Click on either to change its color. To the right of the Color Picker is a palette of default colors. Left-click on one to set it as the primary color and right-click to set as the secondary color. Switch primary and secondary colors by pressing `X`. Reset to default colors (black and white) by pressing `D`. -In the *Edit* menu, palettes can be saved and loaded as `.palette` files. These are text files containing [Hex Color Codes](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet), arranged by line from the top-left color going across. +In the _Edit_ menu, palettes can be saved and loaded as `.palette` files. These are text files containing [Hex Color Codes](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet), arranged by line from the top-left color going across. ### Status Bar + Below the Color Panel is the Status Bar. It displays the pixel coordinates of the cursor when it hovers over the Canvas. When the cursor hovers over the program's interface it describes what a button does. ### Tool Panel -To the left of the main workspace is the Tool Panel which showcases tools available for interacting with the canvas. When a tool is selected, using `[` / `]` adjusts the primary option in the Tool properties panel, e.g. *Size* for the Brush Tool. Adding `Shift` will adjust the secondary option, e.g. *Hardness* for the Brush Tool. -*Hardness* refers to how sharp or abrupt the transition is between painted elements and the background, affecting edge clarity. *Feathered edges* have a softer transition with a gradual decrease in intensity, creating a smooth and blended appearance contrasting with the sharpness of higher hardness. + +To the left of the main workspace is the Tool Panel which showcases tools available for interacting with the canvas. When a tool is selected, using `[` / `]` adjusts the primary option in the Tool properties panel, e.g. _Size_ for the Brush Tool. Adding `Shift` will adjust the secondary option, e.g. _Hardness_ for the Brush Tool. +_Hardness_ refers to how sharp or abrupt the transition is between painted elements and the background, affecting edge clarity. _Feathered edges_ have a softer transition with a gradual decrease in intensity, creating a smooth and blended appearance contrasting with the sharpness of higher hardness. #### Move Tool (`M`) + Moves layers. Select layers either in the Layers Panel or on the canvas. Layers below the top layer can be selected on the canvas if the top layer doesn't fill the entire canvas. #### Pen Tool (`N`) + Paints with a square brush, by default 1px with 100% hardness. Increasing the thickness results in a larger square with 100% hardness. Useful for making pixel art. To draw a straight line, make a mark, hold `Shift` and click elsewhere. #### Brush Tool (`P`) + Paints with a round brush, by default 20px with feathered edges. Size and Hardness can be adjusted. Useful for a more natural appearance. To draw a straight line, make a mark, hold `Shift` and click elsewhere. #### Bucket Tool (`Shift+B`) + Will fill a closed shape, otherwise it will fill the whole layer. #### Spray Tool (`Shift+S`) + Creates a textured effect by scattering pixels randomly within the round brush. The size of and density (how closely packed the pixels are painted) of the spray can be adjusted. Useful for creating fading effects. #### Pick Tool (`O`) -Will make any selected color the primary color. By default, it samples only the active layer unless the option *Sample all layers* is selected. Quickly use at any time by holding `Alt`. + +Will make any selected color the primary color. By default, it samples only the active layer unless the option _Sample all layers_ is selected. Quickly use at any time by holding `Alt`. #### Erase Tool (`Shift+E`) -Erases pixels from the current layer. Has two modes: Pencil (square brush with 100% hardness) and Brush (circular with adjustable hardness). Enabling *Use secondary color* will apply the secondary color instead of making that part of the layer transparent. + +Erases pixels from the current layer. Has two modes: Pencil (square brush with 100% hardness) and Brush (circular with adjustable hardness). Enabling _Use secondary color_ will apply the secondary color instead of making that part of the layer transparent. #### Line Tool (`Ctrl+Shift+L`) + Creates a vector line that is rasterized (converted into a pixel equivalent) upon releasing the mouse. To constrain the angle to 22.5° increments hold `Shift` whilst drawing the line. #### Rectangle Tool (`Ctrl+Shift+R`) + Draws a vector rectangle that is rasterized upon releasing the mouse. To draw a square hold `Shift` whilst drawing the shape. Options: -* **Outline** - Rectangle with no fill. The line thickness can be adjusted. -* **Fill** - Filled with the primary color. -* **Gradient** - Filled with a gradient between the primary and secondary colors, from left-to-right. -* **Rounded** - Draws a vector square with rounded corners that is rasterized upon releasing the mouse. Adjust the corner radius before drawing, as it cannot be changed afterward. -* **Anti-alias** - Smoothens jagged edges for a more polished appearance. -* **Aspect ratio** - Sets the ratio of width and height (e.g. `1` x `1` for a square). + +- **Outline** - Rectangle with no fill. The line thickness can be adjusted. +- **Fill** - Filled with the primary color. +- **Gradient** - Filled with a gradient between the primary and secondary colors, from left-to-right. +- **Rounded** - Draws a vector square with rounded corners that is rasterized upon releasing the mouse. Adjust the corner radius before drawing, as it cannot be changed afterward. +- **Anti-alias** - Smoothens jagged edges for a more polished appearance. +- **Aspect ratio** - Sets the ratio of width and height (e.g. `1` x `1` for a square). #### Ellipse Tool (`Ctrl+Shift+E`) + Draws a vector ellipse that is rasterized upon releasing the mouse. To draw a circle hold `Shift` whilst drawing the shape. Has many of the same options as the Rectangle Tool. #### Text Tool (`Ctrl+Shift+T`) + Click to place the text and start typing. Use `Shift+Enter` to create a new line. Press `Esc` to cancel. The text will use the primary color. Choosing a different color will change the color of the text. Modify the font and font size in the Tool properties. Adjust the text's position while editing. Once you press `Enter` or click away from the text, it will be rasterized and become non-editable. #### Zoom Tool (`Z`) + Left-click to zoom-in, right-click to zoom-out. Adjust the increment size in the Tool properties. #### Selection Tools -Select All with `Ctrl+A`. Press `Esc` to clear a selection. Invert a selection in the *Edit* menu. + +Select All with `Ctrl+A`. Press `Esc` to clear a selection. Invert a selection in the _Edit_ menu. Modes: -* **Set** - Making an initial selection. -* **Add** - Expands the selection area with each new selection, including merging areas. -* **Subtract** - Removes areas from selection. -* **Intersect** - Keeps the overlap with other selections. + +- **Set** - Making an initial selection. +- **Add** - Expands the selection area with each new selection, including merging areas. +- **Subtract** - Removes areas from selection. +- **Intersect** - Keeps the overlap with other selections. ##### Rectangle Select Tool (`R`) + Selects a rectangular-shaped area. Holding `Ctrl` will expand the selection equally on all sides. ##### Wand Select Tool (`W`) + Selects an area based on its color. Adjust the threshold for a more or less precise selection. ##### Polygonal Select Tool (`Shift+P`) -Click to draw the vertices of a polygon. Hold `Shift` to constrain to 22.5° increments. It will become a selected area once a whole shape. Quickly close a shape by double-clicking. *Feathering* can be adjusted, which in this context will give rounded corners. + +Click to draw the vertices of a polygon. Hold `Shift` to constrain to 22.5° increments. It will become a selected area once a whole shape. Quickly close a shape by double-clicking. _Feathering_ can be adjusted, which in this context will give rounded corners. ##### Lasso Select Tool (`L`) + Freehand draw a shape, which will become a selected area once whole. Letting go of the mouse will automatically close the shape. #### Guide Tool (`G`) -Create a guide line by dragging from either of the rulers surrounding the Canvas. Hold `Shift` whilst dragging to do this in 10px increments (adjustable in the Tool properties). Existing guides can be moved. Right-click on a guide to delete it or open the *Set Offset* menu to modify its orientation and offset (the distance in pixels from the top or left-hand ruler). Useful for maintaining alignment when editing. Guide lines are not visible on export. + +Create a guide line by dragging from either of the rulers surrounding the Canvas. Hold `Shift` whilst dragging to do this in 10px increments (adjustable in the Tool properties). Existing guides can be moved. Right-click on a guide to delete it or open the _Set Offset_ menu to modify its orientation and offset (the distance in pixels from the top or left-hand ruler). Useful for maintaining alignment when editing. Guide lines are not visible on export. #### Clone Tool (`C`) + Hold the `Alt` key and click to specify the area to clone (indicated by a green circle). Then paint the clone. Currently it can only clone from the same layer. Size and Hardness of the brush can be adjusted. #### Gradient Tool (`Ctrl+G`) + Click and drag to create a gradient, transitioning from the primary color to transparent by default. Change it to go from the primary to the secondary color in the Tool properties. Adjust the colors in the Color Panel. Move the gradient by grabbing the middle handle and change the size and orientation with the outer handles. Hold `Shift` to constrain to a horizontal or vertical orientation. Press `Enter` to rasterize or `Esc` to cancel. ### Editor Panels -To the right of the main workspace, editor panels facilitate layer configuration, tool adjustments and provide information about the colors in an image. Minimize a panel by double-clicking its name label or using the toggle. Rearrange panels by dragging the name label. Turn them into resizable windows by dragging them out or pressing the detach icon. Turn all of them into a separate window by dragging the *Editor Panels* label out or pressing its detach icon. Turn a detached window back into a panel by closing the window. + +To the right of the main workspace, editor panels facilitate layer configuration, tool adjustments and provide information about the colors in an image. Minimize a panel by double-clicking its name label or using the toggle. Rearrange panels by dragging the name label. Turn them into resizable windows by dragging them out or pressing the detach icon. Turn all of them into a separate window by dragging the _Editor Panels_ label out or pressing its detach icon. Turn a detached window back into a panel by closing the window. The default panels are: -* **Layers** - Add, remove, reorder or manipulate layers. Adjust layers by right-clicking or in the *Layers* menu. - * **Masks** - An overlay that controls a layer's visibility: black hides, white shows and shades of gray provide varying levels of transparency. Masks are non-destructive, allowing reversible edits without permanently altering the original image. Return to the mask menu to delete (completely remove a mask), apply (merge the mask and the underlying layer), invert (reverse the black and white contents) and clear (retain an empty mask layer). -* **Layer properties** - Rename, show/hide or adjust the opacity of a layer. -* **Tool properties** - Configure the settings for the currently selected tool. + +- **Layers** - Add, remove, reorder or manipulate layers. Adjust layers by right-clicking or in the _Layers_ menu. + - **Masks** - An overlay that controls a layer's visibility: black hides, white shows and shades of gray provide varying levels of transparency. Masks are non-destructive, allowing reversible edits without permanently altering the original image. Return to the mask menu to delete (completely remove a mask), apply (merge the mask and the underlying layer), invert (reverse the black and white contents) and clear (retain an empty mask layer). +- **Layer properties** - Rename, show/hide or adjust the opacity of a layer. +- **Tool properties** - Configure the settings for the currently selected tool. #### Color Visualizations + ![Color Visualizations Panels](PixelPaint_Color_Visualizations.png) -Two additional editor panels that visualize color can be enabled in *View → Scopes*: -* **Histogram** - A graph showing the range of color tones in an image, from the darkest on the left to the lightest on the right. As the cursor hovers over the canvas, a yellow line indicates where the pixels under the cursor are represented on the graph. -* **Vectorscope** - Corresponding to the [color wheel](https://en.wikipedia.org/wiki/Color_wheel), the markings indicate the degree of Hue and Saturation in an image. The further the marking from the center, the greater the Saturation. The line going up between red and yellow is the Skin Tone Line indicating the optimal location for all skin tones. As the cursor hovers over the canvas, a circle highlights where the colors are represented on the Vectorscope. +Two additional editor panels that visualize color can be enabled in _View → Scopes_: + +- **Histogram** - A graph showing the range of color tones in an image, from the darkest on the left to the lightest on the right. As the cursor hovers over the canvas, a yellow line indicates where the pixels under the cursor are represented on the graph. +- **Vectorscope** - Corresponding to the [color wheel](https://en.wikipedia.org/wiki/Color_wheel), the markings indicate the degree of Hue and Saturation in an image. The further the marking from the center, the greater the Saturation. The line going up between red and yellow is the Skin Tone Line indicating the optimal location for all skin tones. As the cursor hovers over the canvas, a circle highlights where the colors are represented on the Vectorscope. ### Filters + ![Filter Gallery Window](PixelPaint_Filter_Gallery.png) -In the *Filter* menu is the Filter Gallery which enables adjustment of the whole image (by default), or a selection, by tweaking colors or applying effects. +In the _Filter_ menu is the Filter Gallery which enables adjustment of the whole image (by default), or a selection, by tweaking colors or applying effects. #### Artistic -* **Bloom** - Adds a glow around bright areas. Adjust the glow area brightness threshold and the radius of the glow. + +- **Bloom** - Adds a glow around bright areas. Adjust the glow area brightness threshold and the radius of the glow. #### Edge Detection + Edge detection highlights transitions between visual elements, emphasizing object boundaries. There are two different methods of achieving this: -* **Laplacian Cardinal** - Emphasizes horizontal and vertical edges, accentuating areas with significant intensity changes along these cardinal directions. -* **Laplacian Diagonal** - Emphasizes and highlights diagonal edges in an image, focusing on areas with pronounced intensity changes along diagonal directions. + +- **Laplacian Cardinal** - Emphasizes horizontal and vertical edges, accentuating areas with significant intensity changes along these cardinal directions. +- **Laplacian Diagonal** - Emphasizes and highlights diagonal edges in an image, focusing on areas with pronounced intensity changes along diagonal directions. #### Blur & Sharpen + Various methods exist for producing a blur, leading to varied results. They differ in how they allocate weight, which represents the value assigned to pixels determining their greater or lesser impact on the final image. The Gaussian and Box Blurs offer two choices: `3x3` and `5x5`, indicating the grid size for blur calculation. In simple terms, a larger grid results in a smoother blur. -* **Fast Box Blur** - Quickly blurs an image by averaging the colors of pixels within a defined square area, resulting in a smoother appearance. The blur's radius can be adjusted. Enable *Asymmetric Radii* to adjust the blur along the horizontal, vertical or both axes. Enable *Use Direction and Magnitude* to adjust the blur angle and intensity. The *Approximate Gaussian Blur* option achieves a smoother blur by applying the box blur multiple times with different weights. -* **Gaussian Blur** - Smoothens an image by gradually blending pixel colors based on a bell-shaped distribution, resulting in a softened appearance. -* **Box Blur** - Takes more time than a Fast Box Blur by considering a broader range of neighboring pixels, resulting in a more thorough and refined smoothing. -* **Sharpen** - Enhances the clarity and detail of an image by increasing the contrast at edges, making them more distinct. -* **Median Filter** - Replaces each pixel's value with the median value of its neighboring pixels, providing effective noise reduction while preserving edges and details. Useful for removing dust or defective pixels from an image. + +- **Fast Box Blur** - Quickly blurs an image by averaging the colors of pixels within a defined square area, resulting in a smoother appearance. The blur's radius can be adjusted. Enable _Asymmetric Radii_ to adjust the blur along the horizontal, vertical or both axes. Enable _Use Direction and Magnitude_ to adjust the blur angle and intensity. The _Approximate Gaussian Blur_ option achieves a smoother blur by applying the box blur multiple times with different weights. +- **Gaussian Blur** - Smoothens an image by gradually blending pixel colors based on a bell-shaped distribution, resulting in a softened appearance. +- **Box Blur** - Takes more time than a Fast Box Blur by considering a broader range of neighboring pixels, resulting in a more thorough and refined smoothing. +- **Sharpen** - Enhances the clarity and detail of an image by increasing the contrast at edges, making them more distinct. +- **Median Filter** - Replaces each pixel's value with the median value of its neighboring pixels, providing effective noise reduction while preserving edges and details. Useful for removing dust or defective pixels from an image. #### Color -* **Hue/Saturation** - Precisely adjust the colors in an image by modifying the type of color, its intensity and the amount of black/white mixed in with it. - * **Hue** - The type of color, based on degrees of the color wheel starting from 0% (red). - * **Saturation** - The purity of the color, from 0% (black) to 100% (pure color). - * **Lightness** - The amount of black/white mixed in with the color, from 0% (black) to 100% (white). -* **Grayscale** - Converts an image to black and white by removing the color information, resulting in shades of gray based on the original colors' intensity. -* **Invert** - Transforms an image by reversing the colors, turning dark areas light and vice versa. -* **Sepia** - Makes an image black and white while adding warm, brownish tones, creating a nostalgic or aged appearance reminiscent of old photographs. The intensity can be adjusted. + +- **Hue/Saturation** - Precisely adjust the colors in an image by modifying the type of color, its intensity and the amount of black/white mixed in with it. + - **Hue** - The type of color, based on degrees of the color wheel starting from 0% (red). + - **Saturation** - The purity of the color, from 0% (black) to 100% (pure color). + - **Lightness** - The amount of black/white mixed in with the color, from 0% (black) to 100% (white). +- **Grayscale** - Converts an image to black and white by removing the color information, resulting in shades of gray based on the original colors' intensity. +- **Invert** - Transforms an image by reversing the colors, turning dark areas light and vice versa. +- **Sepia** - Makes an image black and white while adding warm, brownish tones, creating a nostalgic or aged appearance reminiscent of old photographs. The intensity can be adjusted. #### Generic 5x5 Convolution -The last option in the *Filter* menu, a Generic 5x5 Convolution filter alters an image by using a 5x5 grid of numbers to recalculate each pixel's appearance based on its nearby pixels. The *Normalize* option keeps the brightness consistent, maintaining a balanced and normalized appearance. The *Wrap* options makes sure calculations consider pixels on the other side, especially at the image edges, for a smoother effect. Without wrapping, the convolution might produce artifacts or irregularities at the image borders. + +The last option in the _Filter_ menu, a Generic 5x5 Convolution filter alters an image by using a 5x5 grid of numbers to recalculate each pixel's appearance based on its nearby pixels. The _Normalize_ option keeps the brightness consistent, maintaining a balanced and normalized appearance. The _Wrap_ options makes sure calculations consider pixels on the other side, especially at the image edges, for a smoother effect. Without wrapping, the convolution might produce artifacts or irregularities at the image borders. ## Arguments -* `file`: The image file to be edited + +- `file`: The image file to be edited ## Example + ```sh $ PixelPaint /home/anon/Documents/cat.jpg ``` diff --git a/Base/usr/share/man/man1/Applications/Profiler.md b/Base/usr/share/man/man1/Applications/Profiler.md index 7b60a30e108..6856e714300 100644 --- a/Base/usr/share/man/man1/Applications/Profiler.md +++ b/Base/usr/share/man/man1/Applications/Profiler.md @@ -27,11 +27,11 @@ Profiler can also load performance information from previously created ## Options -* `-p PID`, `--pid PID`: PID to profile +- `-p PID`, `--pid PID`: PID to profile ## Arguments -* `perfcore-file`: Path of perfcore file to load +- `perfcore-file`: Path of perfcore file to load ## Examples @@ -49,5 +49,5 @@ $ Profiler perfcore.123 ## See also -* [`perfcore`(5)](help://man/5/perfcore) -* [`profile`(1)](help://man/1/profile) +- [`perfcore`(5)](help://man/5/perfcore) +- [`profile`(1)](help://man/1/profile) diff --git a/Base/usr/share/man/man1/Applications/SQLStudio.md b/Base/usr/share/man/man1/Applications/SQLStudio.md index 626b05c2d62..c48715f1197 100644 --- a/Base/usr/share/man/man1/Applications/SQLStudio.md +++ b/Base/usr/share/man/man1/Applications/SQLStudio.md @@ -17,8 +17,8 @@ SQL scripts. ## Arguments -* `script.sql`: SQL script to open, edit or run -* `database.db`: SQL database to open and run scripts against +- `script.sql`: SQL script to open, edit or run +- `database.db`: SQL database to open and run scripts against ## Examples diff --git a/Base/usr/share/man/man1/Applications/Screenshot.md b/Base/usr/share/man/man1/Applications/Screenshot.md index 6a5f5ac741a..875948fab20 100644 --- a/Base/usr/share/man/man1/Applications/Screenshot.md +++ b/Base/usr/share/man/man1/Applications/Screenshot.md @@ -18,11 +18,11 @@ Its interface remains invisible in screenshots, ensuring a clean capture. ## Options -* **Whole desktop** - Capture the entire user interface, including the cursor if it's visible on the desktop. -* **Selected area** - Click and drag to select a specific area. Release the mouse button to take a screenshot. The cursor will not be included. -* **Edit in Pixel Paint** - Open the screenshot as a new image in [Pixel Paint](help://man/1/Applications/PixelPaint) for quick annotations. -* **Select Folder** - Customize the destination folder for saving screenshots. By default, they are saved in the *Pictures* folder. +- **Whole desktop** - Capture the entire user interface, including the cursor if it's visible on the desktop. +- **Selected area** - Click and drag to select a specific area. Release the mouse button to take a screenshot. The cursor will not be included. +- **Edit in Pixel Paint** - Open the screenshot as a new image in [Pixel Paint](help://man/1/Applications/PixelPaint) for quick annotations. +- **Select Folder** - Customize the destination folder for saving screenshots. By default, they are saved in the _Pictures_ folder. ## See Also -* [`shot`(1)](help://man/1/shot) Command line screenshot tool with more options +- [`shot`(1)](help://man/1/shot) Command line screenshot tool with more options diff --git a/Base/usr/share/man/man1/Applications/Terminal.md b/Base/usr/share/man/man1/Applications/Terminal.md index 81335ce943e..d6b7c58660f 100644 --- a/Base/usr/share/man/man1/Applications/Terminal.md +++ b/Base/usr/share/man/man1/Applications/Terminal.md @@ -18,26 +18,28 @@ It can be launched from the System Menu or the quick access icon to its right, v Select `File → Terminal Settings` to launch the Terminal Settings dialog and display user configurable application properties. This dialog box contains two tabs: View and Terminal. -The *View* tab provides the most frequently sought options: -* Adjust the Terminal font (turn off `Use system default` to select a custom font. -* Specify background opacity, i.e. the amount to which the Terminal's background is transparent, displaying what's underneath. -* Change the shape of the cursor from Block, to Underscore or to Vertical bar. You can also opt to enable or disable cursor's blink property. -* To enable or disable the display of terminal scrollbar. +The _View_ tab provides the most frequently sought options: -The *Terminal* tab gives less frequently used options: -* To either enable System beep, or use Visual bell or disable bell mode altogether. -* To change Terminal's exit behavior +- Adjust the Terminal font (turn off `Use system default` to select a custom font. +- Specify background opacity, i.e. the amount to which the Terminal's background is transparent, displaying what's underneath. +- Change the shape of the cursor from Block, to Underscore or to Vertical bar. You can also opt to enable or disable cursor's blink property. +- To enable or disable the display of terminal scrollbar. -Clicking on the *Apply* button will cause the currently selected options to take effect immediately. +The _Terminal_ tab gives less frequently used options: + +- To either enable System beep, or use Visual bell or disable bell mode altogether. +- To change Terminal's exit behavior + +Clicking on the _Apply_ button will cause the currently selected options to take effect immediately. You can toggle Fullscreen mode by pressing F11. ## Options -* `--help`: Display help message and exit -* `--version`: Print version -* `-e`: Execute this command inside the terminal -* `-k`: Keep the terminal open after the command has finished executing +- `--help`: Display help message and exit +- `--version`: Print version +- `-e`: Execute this command inside the terminal +- `-k`: Keep the terminal open after the command has finished executing ## Examples diff --git a/Base/usr/share/man/man1/Applications/TextEditor.md b/Base/usr/share/man/man1/Applications/TextEditor.md index c58cf310f87..74c0016ffc5 100644 --- a/Base/usr/share/man/man1/Applications/TextEditor.md +++ b/Base/usr/share/man/man1/Applications/TextEditor.md @@ -17,11 +17,11 @@ which allows automatic live rendering of HTML and Markdown documents. ## Options -* `--preview-mode mode`: Preview mode, one of 'none', 'html', 'markdown', 'auto' +- `--preview-mode mode`: Preview mode, one of 'none', 'html', 'markdown', 'auto' ## Arguments -* `file[:line[:column]]`: File to edit, with optional starting line and column number +- `file[:line[:column]]`: File to edit, with optional starting line and column number ## Examples diff --git a/Base/usr/share/man/man1/Shell.md b/Base/usr/share/man/man1/Shell.md index 805b28eb66e..0cbc5e1611d 100644 --- a/Base/usr/share/man/man1/Shell.md +++ b/Base/usr/share/man/man1/Shell.md @@ -24,12 +24,12 @@ The `Shell` utility does not promise POSIX `sh` interoperability. ## Options -* `-c`, `--command-string`: Executes the given string as a command and exits -* `--skip-shellrc`: Skips running the initialization file (at `~/.shellrc`) -* `--format`: Format shell code from the given file and print the result to standard output -* `-f`, `--live-formatting`: Enable live formatting of the line editor buffer (in REPL mode) -* `--keep-open`: Keep the shell open after running the specified command or file -* `--posix`: Behave like a POSIX-compatible shell +- `-c`, `--command-string`: Executes the given string as a command and exits +- `--skip-shellrc`: Skips running the initialization file (at `~/.shellrc`) +- `--format`: Format shell code from the given file and print the result to standard output +- `-f`, `--live-formatting`: Enable live formatting of the line editor buffer (in REPL mode) +- `--keep-open`: Keep the shell open after running the specified command or file +- `--posix`: Behave like a POSIX-compatible shell ## Examples @@ -46,4 +46,4 @@ Shell foo a b c ## See also -* [`Shell-vars`(7)](help://man/7/Shell-vars) For details on local and environment variables used by the shell +- [`Shell-vars`(7)](help://man/7/Shell-vars) For details on local and environment variables used by the shell diff --git a/Base/usr/share/man/man1/abench.md b/Base/usr/share/man/man1/abench.md index cb336d7f717..9d6cc6e72df 100644 --- a/Base/usr/share/man/man1/abench.md +++ b/Base/usr/share/man/man1/abench.md @@ -16,11 +16,11 @@ While `abench` is running, it doesn't report anything to make measurements more ## Options -* `-s`, `--sample-count`: How many samples to load at maximum. This allows you to only benchmark some initial chunk of the file, which is useful when testing on quirky files that happen to be large. +- `-s`, `--sample-count`: How many samples to load at maximum. This allows you to only benchmark some initial chunk of the file, which is useful when testing on quirky files that happen to be large. ## Arguments -* `path`: Path to audio file. As usual, the file type is determined automatically. +- `path`: Path to audio file. As usual, the file type is determined automatically. ## Examples diff --git a/Base/usr/share/man/man1/aconv.md b/Base/usr/share/man/man1/aconv.md index 62ac45bc466..3e58c310593 100644 --- a/Base/usr/share/man/man1/aconv.md +++ b/Base/usr/share/man/man1/aconv.md @@ -22,31 +22,31 @@ By specifying `--audio-format`, `aconv` will use a different sample format for t ### Supported Codecs and Containers -Note that `aconv` currently only supports codecs which have their own bespoke container. Therefore, the distinction does not currently matter. The names given below are the only recognized names for this codec for the command line options `--audio-codec` and `--input-audio-codec`. Some codecs can only be decoded or both encoded and decoded. +Note that `aconv` currently only supports codecs which have their own bespoke container. Therefore, the distinction does not currently matter. The names given below are the only recognized names for this codec for the command line options `--audio-codec` and `--input-audio-codec`. Some codecs can only be decoded or both encoded and decoded. -* `mp3` (decode): MPEG Layer III audio codec and container. -* `wav` (decode, encode): RIFF WAVE audio codec and container. Supports sample formats `u8` and `s16le` for writing. -* `flac` (decode, encode): Free Lossless Audio Codec and container. Supports all integer sample formats for writing. -* `qoa` (decode): Quite Okay Audio codec and container. +- `mp3` (decode): MPEG Layer III audio codec and container. +- `wav` (decode, encode): RIFF WAVE audio codec and container. Supports sample formats `u8` and `s16le` for writing. +- `flac` (decode, encode): Free Lossless Audio Codec and container. Supports all integer sample formats for writing. +- `qoa` (decode): Quite Okay Audio codec and container. ### Supported Sample Formats -* `u8`: Unsigned 8-bit integer -* `s16le`: Signed 16-bit integer, little endian -* `s24le`: Signed 24-bit integer, little endian -* `s32le`: Signed 32-bit integer, little endian -* `f32le`: 32-bit IEEE 754 floating-point number (normalized to the range [-1, 1]), little endian -* `f64le`: 64-bit IEEE 754 floating-point number (normalized to the range [-1, 1]), little endian +- `u8`: Unsigned 8-bit integer +- `s16le`: Signed 16-bit integer, little endian +- `s24le`: Signed 24-bit integer, little endian +- `s32le`: Signed 32-bit integer, little endian +- `f32le`: 32-bit IEEE 754 floating-point number (normalized to the range [-1, 1]), little endian +- `f64le`: 64-bit IEEE 754 floating-point number (normalized to the range [-1, 1]), little endian ## Options The option format follows this general pattern: `--input_or_output-stream-parameter`, where `input_or_output` is either `input` when concerning the input stream, or omitted for the output stream (since this is the more common use case), `stream` currently is always `audio`, and `parameter` is the parameter of the stream that is changed. -* `-i`, `--input`: The input file to convert from. Use `-` to read from standard input. -* `-o`, `--output`: The output file to write to. Use `-` to write to standard output. -* `--input-audio-codec`: Overwrite the used codec and/or sample format of the input file. -* `--audio-codec`: The codec to use for the output file. -* `--audio-format`: The sample format to use for the output file. +- `-i`, `--input`: The input file to convert from. Use `-` to read from standard input. +- `-o`, `--output`: The output file to write to. Use `-` to write to standard output. +- `--input-audio-codec`: Overwrite the used codec and/or sample format of the input file. +- `--audio-codec`: The codec to use for the output file. +- `--audio-format`: The sample format to use for the output file. ## Examples @@ -63,5 +63,5 @@ $ aconv -i ~/music.wav --audio-format u8 -o - ## See Also -* [`abench`(1)](help://man/1/abench) to test audio decoders and measure their performance -* [`aplay`(1)](help://man/1/aplay) to play audio files from the command line +- [`abench`(1)](help://man/1/abench) to test audio decoders and measure their performance +- [`aplay`(1)](help://man/1/aplay) to play audio files from the command line diff --git a/Base/usr/share/man/man1/adjtime.md b/Base/usr/share/man/man1/adjtime.md index 463899ab778..48a647b3a9c 100644 --- a/Base/usr/share/man/man1/adjtime.md +++ b/Base/usr/share/man/man1/adjtime.md @@ -23,8 +23,8 @@ seconds total, not by 2 seconds. ## Options -* `-s delta_seconds`, `--set delta_seconds`: Adjust system time by - `delta_seconds`. Must be superuser. +- `-s delta_seconds`, `--set delta_seconds`: Adjust system time by + `delta_seconds`. Must be superuser. ## Examples diff --git a/Base/usr/share/man/man1/allocate.md b/Base/usr/share/man/man1/allocate.md index 5f43506be78..16cc8ed90de 100644 --- a/Base/usr/share/man/man1/allocate.md +++ b/Base/usr/share/man/man1/allocate.md @@ -18,8 +18,8 @@ It is primarily used to test the kernel's memory management capabilities. ## Options -* `-u`, `--size-unit`: Allocation's Size Unit (Base 2 units - B, KiB, MiB or GiB) -* `-n`, `--sleep-time`: Number of seconds to sleep before freeing memory +- `-u`, `--size-unit`: Allocation's Size Unit (Base 2 units - B, KiB, MiB or GiB) +- `-n`, `--sleep-time`: Number of seconds to sleep before freeing memory ## Examples diff --git a/Base/usr/share/man/man1/aplay.md b/Base/usr/share/man/man1/aplay.md index 0c83bf5eabc..7fcd5c31eaf 100644 --- a/Base/usr/share/man/man1/aplay.md +++ b/Base/usr/share/man/man1/aplay.md @@ -14,12 +14,12 @@ This program plays an audio file specified in `path` through AudioServer. ## Options -* `-l`, `--loop`: Loop playback -* `-s`, `--sample-progress`: Switch to (old-style) sample playback progress. By default, playback is printed as played, remaining and total length, all in minutes and seconds. +- `-l`, `--loop`: Loop playback +- `-s`, `--sample-progress`: Switch to (old-style) sample playback progress. By default, playback is printed as played, remaining and total length, all in minutes and seconds. ## Arguments -* `path`: Path to audio file +- `path`: Path to audio file ## Examples diff --git a/Base/usr/share/man/man1/arp.md b/Base/usr/share/man/man1/arp.md index bd0edb6557f..8f133fd6d01 100644 --- a/Base/usr/share/man/man1/arp.md +++ b/Base/usr/share/man/man1/arp.md @@ -16,14 +16,14 @@ ARP stands for Address Resolution Protocol, which is used to find devices in loc ## Options -* `-s`, `--set`: Set an ARP table entry -* `-d`, `--delete`: Delete an ARP table entry -* `-n`, `--numeric`: Display numerical addresses. Don't resolve hostnames +- `-s`, `--set`: Set an ARP table entry +- `-d`, `--delete`: Delete an ARP table entry +- `-n`, `--numeric`: Display numerical addresses. Don't resolve hostnames ## Arguments -* `address`: IPv4 protocol address -* `hwaddress`: Hardware address +- `address`: IPv4 protocol address +- `hwaddress`: Hardware address ## Examples diff --git a/Base/usr/share/man/man1/asctl.md b/Base/usr/share/man/man1/asctl.md index 43c1fe40fdc..7546ea3f272 100644 --- a/Base/usr/share/man/man1/asctl.md +++ b/Base/usr/share/man/man1/asctl.md @@ -14,12 +14,12 @@ This program is used to send control signals to the AudioServer and the sound ha ## Options -* `-h`, `--human-readable`: Print human-readable output. If this option is not given, the output of `get` will be machine-readable and only consist of one line. +- `-h`, `--human-readable`: Print human-readable output. If this option is not given, the output of `get` will be machine-readable and only consist of one line. ## Arguments -* `command`: The command to execute, either `get` or `set`. -* `args`: The arguments to the command. +- `command`: The command to execute, either `get` or `set`. +- `args`: The arguments to the command. There are two commands available: `get` reports the state of audio variables, and `set` changes these variables. @@ -28,9 +28,10 @@ There are two commands available: `get` reports the state of audio variables, an `set` expects one or more variables followed by a value to set them to, and will set the variables to the given values. A variable can be given multiple times and the last specified value will remain with the audio server. The available variables are: -* `(v)olume`: Audio server volume, in percent. Integer value. -* `(m)ute`: Mute state. Boolean value, may be set with `0`, `false` or `1`, `true`. -* `sample(r)ate`: Sample rate of the sound card. Integer value. + +- `(v)olume`: Audio server volume, in percent. Integer value. +- `(m)ute`: Mute state. Boolean value, may be set with `0`, `false` or `1`, `true`. +- `sample(r)ate`: Sample rate of the sound card. Integer value. Both commands and arguments can be abbreviated: Commands by their first letter, arguments by the letter in parenthesis. diff --git a/Base/usr/share/man/man1/base64.md b/Base/usr/share/man/man1/base64.md index c02df51df91..b69a285730c 100644 --- a/Base/usr/share/man/man1/base64.md +++ b/Base/usr/share/man/man1/base64.md @@ -15,8 +15,8 @@ file is not specified or file is `-`. ## Options -* `-d`, `--decode`: Decode data -* `-w column`, `--wrap column`: When encoding, wrap output after `column` characters +- `-d`, `--decode`: Decode data +- `-w column`, `--wrap column`: When encoding, wrap output after `column` characters ## Examples diff --git a/Base/usr/share/man/man1/basename.md b/Base/usr/share/man/man1/basename.md index 5064bf5c18e..b3ee970cf62 100644 --- a/Base/usr/share/man/man1/basename.md +++ b/Base/usr/share/man/man1/basename.md @@ -14,8 +14,8 @@ $ basename [suffix] ## Arguments -* `path`: The path which we want to get basename of -* `suffix`: Suffix to strip from name +- `path`: The path which we want to get basename of +- `suffix`: Suffix to strip from name ## Examples diff --git a/Base/usr/share/man/man1/beep.md b/Base/usr/share/man/man1/beep.md index dd08bb4f058..4a5d370e493 100644 --- a/Base/usr/share/man/man1/beep.md +++ b/Base/usr/share/man/man1/beep.md @@ -14,8 +14,8 @@ beep allows the user to beep the PC speaker. ## Options -* `-f frequency`, `--beep-tone frequency`: Beep tone (frequency in Hz) -* `-n N`, `--duration N`: Duration (N in milliseconds) +- `-f frequency`, `--beep-tone frequency`: Beep tone (frequency in Hz) +- `-n N`, `--duration N`: Duration (N in milliseconds) ## Notes @@ -35,4 +35,4 @@ $ beep -f 1000 -n 1000 ## See also -* [`boot_parameters`(7)](help://man/7/boot_parameters) +- [`boot_parameters`(7)](help://man/7/boot_parameters) diff --git a/Base/usr/share/man/man1/bt.md b/Base/usr/share/man/man1/bt.md index 3974937a7fd..02a142cfbb1 100644 --- a/Base/usr/share/man/man1/bt.md +++ b/Base/usr/share/man/man1/bt.md @@ -16,14 +16,14 @@ addresses for each frame in the stack producing a backtrace. **NOTE**: -* Kernel addresses will not be available unless you are super user. +- Kernel addresses will not be available unless you are super user. -* If Kernel addresses are available, they will not be symbolicated unless - the current user has access to the `/boot/Kernel` file. +- 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 +- `pid`: Process ID ## Examples @@ -41,6 +41,6 @@ $ watch -n 1 -- bt 124 ## See also -* [`Profiler`(1)](help://man/1/Applications/Profiler) +- [`Profiler`(1)](help://man/1/Applications/Profiler) -* [`watch`(1)](help://man/1/watch) +- [`watch`(1)](help://man/1/watch) diff --git a/Base/usr/share/man/man1/cal.md b/Base/usr/share/man/man1/cal.md index 409a4e6d541..eec14399752 100644 --- a/Base/usr/share/man/man1/cal.md +++ b/Base/usr/share/man/man1/cal.md @@ -22,9 +22,9 @@ Days, months and years are specified with numbers. Week starts at Sunday. ## Options -* `-s`, `--starting-day`: Specify which day should start the week. Accepts either short or long weekday names or indexes (0 being Sunday). -* `-3`, `--three-month-view`: Display the previous, current, and next months side-by-side. -* `-y`, `--year`: Display an entire year by laying out months on a grid. If no year number is specified, the current year is used as a default. +- `-s`, `--starting-day`: Specify which day should start the week. Accepts either short or long weekday names or indexes (0 being Sunday). +- `-3`, `--three-month-view`: Display the previous, current, and next months side-by-side. +- `-y`, `--year`: Display an entire year by laying out months on a grid. If no year number is specified, the current year is used as a default. ## Examples @@ -48,7 +48,7 @@ Su Mo Tu We Th Fr Sa 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 -31 +31 # Display three months side-by-side $ cal -3 3 2023 diff --git a/Base/usr/share/man/man1/cat.md b/Base/usr/share/man/man1/cat.md index e0e4bcd6a78..c3f634b029b 100644 --- a/Base/usr/share/man/man1/cat.md +++ b/Base/usr/share/man/man1/cat.md @@ -14,7 +14,7 @@ This program passes contents of specified `files` to standard output, in the spe ## Arguments -* `file`: Files to print +- `file`: Files to print ## Examples @@ -53,6 +53,7 @@ cat test.txt test2.txt ``` ## See Also -* [`head`(1)](help://man/1/head) -* [`tail`(1)](help://man/1/tail) -* [`cut`(1)](help://man/1/cut) + +- [`head`(1)](help://man/1/head) +- [`tail`(1)](help://man/1/tail) +- [`cut`(1)](help://man/1/cut) diff --git a/Base/usr/share/man/man1/checksum.md b/Base/usr/share/man/man1/checksum.md index 2bb7ca02e29..3e1adbbed1d 100644 --- a/Base/usr/share/man/man1/checksum.md +++ b/Base/usr/share/man/man1/checksum.md @@ -7,10 +7,10 @@ checksum - helper program for calculating checksums ```**sh $ b2sum [options...] $ md5sum [options...] -$ sha1sum [options...] -$ sha256sum [options...] +$ sha1sum [options...] +$ sha256sum [options...] $ sha512sum [options...] -``` +``` ## Description @@ -21,4 +21,4 @@ if the checksums cannot be verified. ## Options -* `-c`, `--check`: Verify checksums against `file` or stdin. +- `-c`, `--check`: Verify checksums against `file` or stdin. diff --git a/Base/usr/share/man/man1/chgrp.md b/Base/usr/share/man/man1/chgrp.md index 0725e2f343c..96231bd025c 100644 --- a/Base/usr/share/man/man1/chgrp.md +++ b/Base/usr/share/man/man1/chgrp.md @@ -15,7 +15,7 @@ $ chgrp ## Options -* `-h`, `--no-dereference`: Don't follow symlinks +- `-h`, `--no-dereference`: Don't follow symlinks ## Examples @@ -29,5 +29,5 @@ $ chgrp ## See also -* [`chmod`(1)](help://man/1/chmod) -* [`chown`(1)](help://man/1/chown) +- [`chmod`(1)](help://man/1/chmod) +- [`chown`(1)](help://man/1/chown) diff --git a/Base/usr/share/man/man1/chmod.md b/Base/usr/share/man/man1/chmod.md index b068f8234c2..9e3336606c8 100644 --- a/Base/usr/share/man/man1/chmod.md +++ b/Base/usr/share/man/man1/chmod.md @@ -25,7 +25,7 @@ A numeric mode is combination of 1 to 4 numbers. Omitted digits are assumed to b ## Options -* `-R`, `--recursive`: Change file modes recursively +- `-R`, `--recursive`: Change file modes recursively ## Examples @@ -48,5 +48,5 @@ $ chmod g=r script.sh ## See also -* [`chgrp`(1)](help://man/1/chgrp) -* [`chown`(1)](help://man/1/chown) +- [`chgrp`(1)](help://man/1/chgrp) +- [`chown`(1)](help://man/1/chown) diff --git a/Base/usr/share/man/man1/chown.md b/Base/usr/share/man/man1/chown.md index b2f6398713d..aa16fd9f16e 100644 --- a/Base/usr/share/man/man1/chown.md +++ b/Base/usr/share/man/man1/chown.md @@ -17,9 +17,9 @@ group. ## Options -* `-h`, `--no-dereference`: Don't follow symlinks -* `-R`, `--recursive`: Change file ownership recursively -* `-L`: Follow symlinks while recursing into directories +- `-h`, `--no-dereference`: Don't follow symlinks +- `-R`, `--recursive`: Change file ownership recursively +- `-L`: Follow symlinks while recursing into directories ## Examples @@ -33,5 +33,5 @@ $ chown anon:anon file ## See also -* [`chgrp`(1)](help://man/1/chgrp) -* [`chmod`(1)](help://man/1/chmod) +- [`chgrp`(1)](help://man/1/chgrp) +- [`chmod`(1)](help://man/1/chmod) diff --git a/Base/usr/share/man/man1/chres.md b/Base/usr/share/man/man1/chres.md index 75acb48964d..308cf9344b1 100644 --- a/Base/usr/share/man/man1/chres.md +++ b/Base/usr/share/man/man1/chres.md @@ -14,7 +14,7 @@ $ chres [scale factor] ## Options -* `-s`, `--screen`: Screen +- `-s`, `--screen`: Screen ## Examples @@ -25,4 +25,4 @@ $ chres 1920 1080 2 ## Files -* `/tmp/portal/window` to communicate with WindowServer +- `/tmp/portal/window` to communicate with WindowServer diff --git a/Base/usr/share/man/man1/cmp.md b/Base/usr/share/man/man1/cmp.md index a89d563da99..b3be4e3cd4b 100644 --- a/Base/usr/share/man/man1/cmp.md +++ b/Base/usr/share/man/man1/cmp.md @@ -10,23 +10,24 @@ $ cmp [options...] file1 file2 ## Description -Compare two files and report the location of any differences. By default, execution stops after the first difference, but this can be overridden (see `--verbose` option). Byte and line numbers start at 1. +Compare two files and report the location of any differences. By default, execution stops after the first difference, but this can be overridden (see `--verbose` option). Byte and line numbers start at 1. ## Options -* `--help`: Display help message and exit -* `-l`, `--verbose`: Output the byte number, and the differing bytes, for every difference. -* `-s`, `--silent`: Silence output. +- `--help`: Display help message and exit +- `-l`, `--verbose`: Output the byte number, and the differing bytes, for every difference. +- `-s`, `--silent`: Silence output. ## Arguments -* `file1` and `file2`: Files to compare. Use `-` as the file name to read from standard input. +- `file1` and `file2`: Files to compare. Use `-` as the file name to read from standard input. ## Exit status -* 0 - Files are identical. -* 1 - Files are different. -* 2 - An error occurred. +- 0 - Files are identical. +- 1 - Files are different. +- 2 - An error occurred. ## See also -* [`comm`(1)](help://man/1/comm) + +- [`comm`(1)](help://man/1/comm) diff --git a/Base/usr/share/man/man1/comm.md b/Base/usr/share/man/man1/comm.md index dfed693c800..622333cde99 100644 --- a/Base/usr/share/man/man1/comm.md +++ b/Base/usr/share/man/man1/comm.md @@ -16,18 +16,18 @@ With no options, `comm` produces a three column output, indented by tabs, of lin ## Options -* `-1`: Suppress the output of column 1 (lines unique to `file1`) -* `-2`: Suppress the output of column 2 (lines unique to `file2`) -* `-3`: Suppress the output of column 3 (lines common to `file1` and `file2`) -* `-i`: Use case insensitive comparison of lines -* `-c`, `--color`: Always print colored output even if the standard output is not a tty -* `--no-color`: Do not print colored output -* `-t`, `--total`: Print a summary +- `-1`: Suppress the output of column 1 (lines unique to `file1`) +- `-2`: Suppress the output of column 2 (lines unique to `file2`) +- `-3`: Suppress the output of column 3 (lines common to `file1` and `file2`) +- `-i`: Use case insensitive comparison of lines +- `-c`, `--color`: Always print colored output even if the standard output is not a tty +- `--no-color`: Do not print colored output +- `-t`, `--total`: Print a summary ## Arguments -* `file1`: First file to compare. (`-` for the standard input) -* `file2`: Second file to compare. (`-` for the standard input) +- `file1`: First file to compare. (`-` for the standard input) +- `file2`: Second file to compare. (`-` for the standard input) ## Examples @@ -50,4 +50,5 @@ $ comm -123it file1_sorted file2_sorted ``` ## See also -* [`cmp`(1)](help://man/1/cmp) + +- [`cmp`(1)](help://man/1/cmp) diff --git a/Base/usr/share/man/man1/config.md b/Base/usr/share/man/man1/config.md index 5685d6797b5..c0ee0c21568 100644 --- a/Base/usr/share/man/man1/config.md +++ b/Base/usr/share/man/man1/config.md @@ -14,13 +14,13 @@ Show or modify values in the configuration files through ConfigServer. ## Options -* `-r`, `--remove`: Remove group or key +- `-r`, `--remove`: Remove group or key ## Arguments -* `domain`: Config domain -* `group`: Group name -* `key`: Key name -* `value`: Value to write +- `domain`: Config domain +- `group`: Group name +- `key`: Key name +- `value`: Value to write diff --git a/Base/usr/share/man/man1/copy.md b/Base/usr/share/man/man1/copy.md index f957e861fd0..d02c8a83fee 100644 --- a/Base/usr/share/man/man1/copy.md +++ b/Base/usr/share/man/man1/copy.md @@ -14,8 +14,8 @@ $ copy [options...] [text...] ## 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. +- `-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 @@ -28,4 +28,5 @@ $ copy foo ``` ## See also -* [`clipboard`(5)](help://man/5/clipboard) + +- [`clipboard`(5)](help://man/5/clipboard) diff --git a/Base/usr/share/man/man1/cp.md b/Base/usr/share/man/man1/cp.md index 40bc35898bf..130c8d7a80f 100644 --- a/Base/usr/share/man/man1/cp.md +++ b/Base/usr/share/man/man1/cp.md @@ -18,9 +18,9 @@ If a directory is specified in `source`, the `-R` (recursive) flag is required. ## Options -* `-l`, `--link`: Create hard links instead of copying -* `-R`, `-r`, `--recursive`: Copy directories recursively -* `-v`, `--verbose`: Display what files are copied +- `-l`, `--link`: Create hard links instead of copying +- `-R`, `-r`, `--recursive`: Copy directories recursively +- `-v`, `--verbose`: Display what files are copied ## Examples @@ -36,4 +36,5 @@ $ cp test root ``` ## See also -* [`mv`(1)](help://man/1/mv) + +- [`mv`(1)](help://man/1/mv) diff --git a/Base/usr/share/man/man1/crash.md b/Base/usr/share/man/man1/crash.md index e448f7d3b7f..dceb9fdf813 100644 --- a/Base/usr/share/man/man1/crash.md +++ b/Base/usr/share/man/man1/crash.md @@ -16,38 +16,39 @@ and can be used to simulate many different kinds of crashes. Some crash tests are only available on certain architectures. Some crash tests are excluded from the `-A` test, since depending on the hardware or implementation they may or may not crash. -- Priviledged instructions in user mode are permitted by QEMU on some architectures such as x86. Therefore, this crash may not fail. See [discussion on pull request 10042](https://github.com/SerenityOS/serenity/pull/10042#issuecomment-920408568). + +- Priviledged instructions in user mode are permitted by QEMU on some architectures such as x86. Therefore, this crash may not fail. See [discussion on pull request 10042](https://github.com/SerenityOS/serenity/pull/10042#issuecomment-920408568). ## Options All architectures: -* `-A`: Test that all of the crash types implemented on this architecture crash as expected. -* `-s`: Perform a segmentation violation by dereferencing an invalid pointer. -* `-i`: Execute an illegal CPU instruction. -* `-a`: Call `abort()`. -* `-m`: Read a pointer from uninitialized malloc memory, then read from it. -* `-f`: Read a pointer from memory freed using `free()`, then read from it. -* `-M`: Read a pointer from uninitialized malloc memory, then write to it. -* `-F`: Read a pointer from memory freed using `free()`, then write to it. -* `-r`: Write to read-only memory. -* `-T`: Make a syscall while using an invalid stack pointer. -* `-t`: Trigger a page fault while using an invalid stack pointer. -* `-S`: Make a syscall from writeable memory. -* `-y`: Make a syscall from legitimate memory (but outside syscall-code mapped region). -* `-X`: Attempt to execute non-executable memory (Not mapped with PROT\_EXEC). -* `-U`: Attempt to use a priviledged (kernel mode or higher) instruction in user mode. -* `-p`: Violate `pledge()`'d promises. -* `-n`: Perform a failing assertion. -* `-R`: Dereference a null RefPtr. +- `-A`: Test that all of the crash types implemented on this architecture crash as expected. +- `-s`: Perform a segmentation violation by dereferencing an invalid pointer. +- `-i`: Execute an illegal CPU instruction. +- `-a`: Call `abort()`. +- `-m`: Read a pointer from uninitialized malloc memory, then read from it. +- `-f`: Read a pointer from memory freed using `free()`, then read from it. +- `-M`: Read a pointer from uninitialized malloc memory, then write to it. +- `-F`: Read a pointer from memory freed using `free()`, then write to it. +- `-r`: Write to read-only memory. +- `-T`: Make a syscall while using an invalid stack pointer. +- `-t`: Trigger a page fault while using an invalid stack pointer. +- `-S`: Make a syscall from writeable memory. +- `-y`: Make a syscall from legitimate memory (but outside syscall-code mapped region). +- `-X`: Attempt to execute non-executable memory (Not mapped with PROT_EXEC). +- `-U`: Attempt to use a priviledged (kernel mode or higher) instruction in user mode. +- `-p`: Violate `pledge()`'d promises. +- `-n`: Perform a failing assertion. +- `-R`: Dereference a null RefPtr. x86_64 only: -* `-I`: Use an x86 I/O instruction in userspace. +- `-I`: Use an x86 I/O instruction in userspace. AArch64 and x86_64 only: -* `-d`: Perform a division by zero. +- `-d`: Perform a division by zero. ## Examples diff --git a/Base/usr/share/man/man1/cut.md b/Base/usr/share/man/man1/cut.md index 1444399aff1..ed54894853f 100644 --- a/Base/usr/share/man/man1/cut.md +++ b/Base/usr/share/man/man1/cut.md @@ -16,14 +16,14 @@ With no FILE, or when FILE is -, read standard input. ## Arguments -* `file`: File(s) to cut +- `file`: File(s) to cut ## Options -* `-b` `--bytes=list`: Select only these bytes -* `-f` `--fields=list`: select only these fields; also print any line that contains no delimiter character -* `-d` `--delimiter=delim`: use `delim` instead of `tab` for field delimiter -* `-s`, `only-delimited`: suppress lines which don't contain any field delimiter characters +- `-b` `--bytes=list`: Select only these bytes +- `-f` `--fields=list`: select only these fields; also print any line that contains no delimiter character +- `-d` `--delimiter=delim`: use `delim` instead of `tab` for field delimiter +- `-s`, `only-delimited`: suppress lines which don't contain any field delimiter characters ## Examples @@ -37,17 +37,18 @@ $ cut example.txt -f 1,3 245:789 M:4540 535:763 M:3476 -# Display first and third fields using `:` as a delimiter +# Display first and third fields using `:` as a delimiter $ cut example.txt -d ':' -f 1,3 245:4540 Admin 01 535:3476 Sales 11 -# Display bytes at given position +# Display bytes at given position $ echo "serenity is cool" | cut -b 5 n ``` ## See Also -* [`head`(1)](help://man/1/head) -* [`cat`(1)](help://man/1/cat) + +- [`head`(1)](help://man/1/head) +- [`cat`(1)](help://man/1/cat) diff --git a/Base/usr/share/man/man1/date.md b/Base/usr/share/man/man1/date.md index fb5c999ec1f..2825cc03283 100644 --- a/Base/usr/share/man/man1/date.md +++ b/Base/usr/share/man/man1/date.md @@ -15,15 +15,15 @@ or print the system date and time in various formats. ## Options -* `-s`, `--set`: Set system date and time -* `-u`, `--unix`: Print date as Unix timestamp -* `-i`, `--iso-8601`: Print date in ISO 8601 format -* `-r`, `--rfc-3339`: Print date in RFC 3339 format -* `-R`, `--rfc-5322`: Print date in RFC 5322 format +- `-s`, `--set`: Set system date and time +- `-u`, `--unix`: Print date as Unix timestamp +- `-i`, `--iso-8601`: Print date in ISO 8601 format +- `-r`, `--rfc-3339`: Print date in RFC 3339 format +- `-R`, `--rfc-5322`: Print date in RFC 5322 format ## Arguments -* `format-string`: Custom format to print the date in. Must start with a '+' character. +- `format-string`: Custom format to print the date in. Must start with a '+' character. ## Examples @@ -39,4 +39,5 @@ $ date -s 1610017485 ``` ## See Also -* [`ntpquery`(1)](help://man/1/ntpquery) + +- [`ntpquery`(1)](help://man/1/ntpquery) diff --git a/Base/usr/share/man/man1/dd.md b/Base/usr/share/man/man1/dd.md index 03447072937..06b5fe5beb9 100644 --- a/Base/usr/share/man/man1/dd.md +++ b/Base/usr/share/man/man1/dd.md @@ -14,20 +14,20 @@ $ dd if=[input_file] of=[output_file] [args...] ## Options -* `--help`: Display help message and exit +- `--help`: Display help message and exit ## Arguments -* `if`: input file (or device) to read from (default: stdin) -* `of`: output file (or device) to write to (default: stdout) -* `bs`: block size (of bytes) to use (default: 512) -* `count`: number of blocks to write -* `seek`: number of output blocks to skip (default: 0) -* `skip`: number of input blocks to skip (default: 0) -* `status`: level of output (default: default) - * `default`: error messages + final statistics - * `none`: just error messages - * `noxfer`: no final statistics +- `if`: input file (or device) to read from (default: stdin) +- `of`: output file (or device) to write to (default: stdout) +- `bs`: block size (of bytes) to use (default: 512) +- `count`: number of blocks to write +- `seek`: number of output blocks to skip (default: 0) +- `skip`: number of input blocks to skip (default: 0) +- `status`: level of output (default: default) + - `default`: error messages + final statistics + - `none`: just error messages + - `noxfer`: no final statistics ## Examples diff --git a/Base/usr/share/man/man1/diff.md b/Base/usr/share/man/man1/diff.md index 000c79348da..de17d3d72ce 100644 --- a/Base/usr/share/man/man1/diff.md +++ b/Base/usr/share/man/man1/diff.md @@ -14,12 +14,12 @@ Compare `files` line by line. ## Arguments -* `files`: files to compare ex: `file1 file2` +- `files`: files to compare ex: `file1 file2` ## Options -* `-u`, `-U `, `--unified `: Write diff in unified format with `` number of surrounding context lines (default 3). -* `-c`, `-C `, `--context `: Write diff in context format with `` number of surrounding context lines (default 3). +- `-u`, `-U `, `--unified `: Write diff in unified format with `` number of surrounding context lines (default 3). +- `-c`, `-C `, `--context `: Write diff in context format with `` number of surrounding context lines (default 3). ## Examples diff --git a/Base/usr/share/man/man1/dirname.md b/Base/usr/share/man/man1/dirname.md index 35a2d98ce3c..c099a4a31fc 100644 --- a/Base/usr/share/man/man1/dirname.md +++ b/Base/usr/share/man/man1/dirname.md @@ -10,9 +10,8 @@ $ dirname [--zero] ## Options -* `-z`, `--zero`: End each output line with \0, rather than \n +- `-z`, `--zero`: End each output line with \0, rather than \n ## Arguments -* `path`: Path - +- `path`: Path diff --git a/Base/usr/share/man/man1/drain.md b/Base/usr/share/man/man1/drain.md index a23c8349be9..4d90316a25e 100644 --- a/Base/usr/share/man/man1/drain.md +++ b/Base/usr/share/man/man1/drain.md @@ -18,11 +18,11 @@ The output may be redirected to another file or utility for further processing. ## Options -* `-b`, `--block-size`: Base block size [in KiB] to be used during the utility operation, default is 256 KiB +- `-b`, `--block-size`: Base block size [in KiB] to be used during the utility operation, default is 256 KiB ## Arguments -* `file`: File to be read +- `file`: File to be read ## Warning diff --git a/Base/usr/share/man/man1/du.md b/Base/usr/share/man/man1/du.md index 30a778cc14f..b1896d2ef00 100644 --- a/Base/usr/share/man/man1/du.md +++ b/Base/usr/share/man/man1/du.md @@ -14,24 +14,24 @@ $ du [files...] ## Options -* `-a`, `--all`: Write counts for all files, not just directories -* `--apparent-size`: Print apparent sizes, rather than disk usage -* `-c`, `--total`: Print total size in the end -* `-h` , `--human-readable`: Print human-readable sizes -* `--si`: Print human-readable sizes in SI units -* `-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`, `--one-file-system`: Don't traverse directories on different file systems -* `-X file, --exclude-from`: Exclude files that match any pattern in file -* `--max-size`: Exclude files with size above a specified size -* `--min-size`: Exclude files with size below a specified size +- `-a`, `--all`: Write counts for all files, not just directories +- `--apparent-size`: Print apparent sizes, rather than disk usage +- `-c`, `--total`: Print total size in the end +- `-h` , `--human-readable`: Print human-readable sizes +- `--si`: Print human-readable sizes in SI units +- `-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`, `--one-file-system`: Don't traverse directories on different file systems +- `-X file, --exclude-from`: Exclude files that match any pattern in file +- `--max-size`: Exclude files with size above a specified size +- `--min-size`: Exclude files with size below a specified size ## Arguments -* `files`: Files to print disk usage of +- `files`: Files to print disk usage of ## Examples diff --git a/Base/usr/share/man/man1/echo.md b/Base/usr/share/man/man1/echo.md index a66411c0aee..161646fb0c0 100644 --- a/Base/usr/share/man/man1/echo.md +++ b/Base/usr/share/man/man1/echo.md @@ -42,8 +42,8 @@ Character escape sequences and their meanings are as follows: ## Options -* `-n`: Do not output a trailing newline -* `-e`: Interpret backslash escapes +- `-n`: Do not output a trailing newline +- `-e`: Interpret backslash escapes ## Examples diff --git a/Base/usr/share/man/man1/elfdeps.md b/Base/usr/share/man/man1/elfdeps.md index de6f41fcfbc..80207d96cf3 100644 --- a/Base/usr/share/man/man1/elfdeps.md +++ b/Base/usr/share/man/man1/elfdeps.md @@ -14,19 +14,19 @@ $ elfdeps [-r] [-f] ## Options -* `-f`, `--force-without-valid-interpreter`: Force library resolving on ELF +- `-f`, `--force-without-valid-interpreter`: Force library resolving on ELF object without a valid interpreter -* `-r`, `--max-recursion`: Max library resolving recursion -* `-s`, `--path-only-format`: Use Path-only format printing +- `-r`, `--max-recursion`: Max library resolving recursion +- `-s`, `--path-only-format`: Use Path-only format printing ## Arguments -* `path`: Path to ELF object +- `path`: Path to ELF object ## Security -The `elfdeps` binary is completely safe for usage on untrusted binaries - -we only use the `LibELF` code for doing library resolving, and the actual +The `elfdeps` binary is completely safe for usage on untrusted binaries - +we only use the `LibELF` code for doing library resolving, and the actual binary interpreter (when specified in an ELF exectuable) is never called to decode the dependency information. diff --git a/Base/usr/share/man/man1/env.md b/Base/usr/share/man/man1/env.md index e0191b945a1..fdabf7e84de 100644 --- a/Base/usr/share/man/man1/env.md +++ b/Base/usr/share/man/man1/env.md @@ -10,10 +10,10 @@ $ env [--ignore-environment] [--split-string S] [--unset name] [env/command...] ## Options -* `-i`, `--ignore-environment`: Start with an empty environment -* `-S S`, `--split-string S`: Process and split S into separate arguments; used to pass multiple arguments on shebang lines -* `-u name`, `--unset name`: Remove variable from the environment +- `-i`, `--ignore-environment`: Start with an empty environment +- `-S S`, `--split-string S`: Process and split S into separate arguments; used to pass multiple arguments on shebang lines +- `-u name`, `--unset name`: Remove variable from the environment ## Arguments -* `env/command`: Environment and commands +- `env/command`: Environment and commands diff --git a/Base/usr/share/man/man1/expr.md b/Base/usr/share/man/man1/expr.md index be325fabbaf..c3bf4bdd7cb 100644 --- a/Base/usr/share/man/man1/expr.md +++ b/Base/usr/share/man/man1/expr.md @@ -10,48 +10,50 @@ $ expr [--help] ``` ## Description + expr evaluates and prints the result of an expression as described below to standard output. An _expression_ may be any of the following: -- `expr1 | expr2` + +- `expr1 | expr2` `expr2` if `expr1` is falsy, `expr1` otherwise. -- `expr1 & expr2` +- `expr1 & expr2` `expr1` if neither expression is falsy, `0` otherwise. -- `expr1 < expr2` +- `expr1 < expr2` `1` if `expr1` is less than `expr2`, `0` otherwise. -- `expr1 <= expr2` +- `expr1 <= expr2` `1` if `expr1` is less than or equal to `expr2`, `0` otherwise. -- `expr1 = expr2` +- `expr1 = expr2` `1` if `expr1` is equal to `expr2`, `0` otherwise. -- `expr1 = expr2` +- `expr1 = expr2` `1` if `expr1` is not equal to `expr2`, `0` otherwise. -- `expr1 => expr2` +- `expr1 => expr2` `1` if `expr1` is greater than or equal to `expr2`, `0` otherwise. -- `expr1 > expr2` +- `expr1 > expr2` `1` if `expr1` is greater than `expr2`, `0` otherwise. -- `expr1 + expr2` +- `expr1 + expr2` arithmetic integral sum of `expr1` and `expr2`. -- `expr1 - expr2` +- `expr1 - expr2` arithmetic integral difference of `expr1` and `expr2`. -- `expr1 * expr2` +- `expr1 * expr2` arithmetic integral product of `expr1` and `expr2`. -- `expr1 / expr2` +- `expr1 / expr2` arithmetic integral quotient of `expr1` divided by `expr2`. -- `expr1 % expr2` +- `expr1 % expr2` arithmetic integral quotient of `expr1` divided by `expr2`. -- `expr1 : expr2` +- `expr1 : expr2` pattern match of `expr2` as a regular expression in `expr1` - currently not implemented. -- `match expr1 expr2` +- `match expr1 expr2` same as `expr1 : expr2`. -- `substr expr1 expr2 expr3` +- `substr expr1 expr2 expr3` substring with length `expr3` of `expr1`, starting at `expr2`, indices starting at 1. -- `index expr1 expr2` +- `index expr1 expr2` index of `expr2` in `expr1`, starting at 1. 0 if not found. -- `length expr1` +- `length expr1` length of the string `expr1` -- `+ token` +- `+ token` interpret `token` as a string, regardless of whether it is a keyword or an operator. -- `( expr )` +- `( expr )` value of `expr` Note that many operators will need to be escaped or quoted if used from within a shell. @@ -59,7 +61,7 @@ Note that many operators will need to be escaped or quoted if used from within a ## Options -* `--help`: Prints usage information and exits. +- `--help`: Prints usage information and exits. ## Examples @@ -70,5 +72,6 @@ $ expr substr foobar 1 3 # foo ``` ## See also -* [`test`(1)](help://man/1/test) -* [`js`(1)](help://man/1/js) for evaluating more complex expressions + +- [`test`(1)](help://man/1/test) +- [`js`(1)](help://man/1/js) for evaluating more complex expressions diff --git a/Base/usr/share/man/man1/file.md b/Base/usr/share/man/man1/file.md index db41f5cc0c8..1d5e3c31e5b 100644 --- a/Base/usr/share/man/man1/file.md +++ b/Base/usr/share/man/man1/file.md @@ -16,13 +16,13 @@ First, an attempt is made to identify a given file based on predetermined binary ## Options -* `--help`: Display this message -* `-b`, `--brief`: Do not prepend file names to output lines -* `-I`, `--mime-type`: Only show mime type. +- `--help`: Display this message +- `-b`, `--brief`: Do not prepend file names to output lines +- `-I`, `--mime-type`: Only show mime type. ## Arguments -* `files`: Files to identify +- `files`: Files to identify ## Examples @@ -33,4 +33,3 @@ Buggie.png: PNG image data, 64 x 138 # Identify all files in the current directory, and show only the mime type. $ file -I * ``` - diff --git a/Base/usr/share/man/man1/find.md b/Base/usr/share/man/man1/find.md index 46a172c5085..9cf4fed4bad 100644 --- a/Base/usr/share/man/man1/find.md +++ b/Base/usr/share/man/man1/find.md @@ -15,105 +15,106 @@ $ find [-L] [root-paths...] [commands...] evaluates the given commands for each found file. The commands can be used to both filter the set of files and to perform actions on them. -If no *action command* (`-print`, `-print0`, or `-exec`) is found among the +If no _action command_ (`-print`, `-print0`, or `-exec`) is found among the specified commands, a `-print` command is implicitly appended. ## Options -* `-L`: Follow symlinks +- `-L`: Follow symlinks ## Commands -* `-maxdepth n`: Do not descend more than `n` levels below each path given on - the command line. Specifying `-maxdepth 0` has the effect of only evaluating - each command line argument. -* `-mindepth n`: Descend `n` levels below each path given on the command line - before executing any commands. Specifying `-mindepth 1` has the effect of - processing all files except the command line arguments. -* `-type t`: Checks if the file is of the specified type, which must be one of - `b` (for block device), `c` (character device), `d` (directory), `l` (symbolic - link), `p` (FIFO), `f` (regular file), and `s` (socket). -* `-links [-|+]number`: Checks if the file has the given number of hard links. -* `-user name`: Checks if the file is owned by the given user. Instead of a user - name, a numerical UID may be specified. -* `-group name`: Checks if the file is owned by the given group. Instead of a - group name, a numerical GID may be specified. -* `-size [-|+]number[bcwkMG]`: Checks if the file uses the specified `n` units of - space rounded up to the nearest whole unit. +- `-maxdepth n`: Do not descend more than `n` levels below each path given on + the command line. Specifying `-maxdepth 0` has the effect of only evaluating + each command line argument. +- `-mindepth n`: Descend `n` levels below each path given on the command line + before executing any commands. Specifying `-mindepth 1` has the effect of + processing all files except the command line arguments. +- `-type t`: Checks if the file is of the specified type, which must be one of + `b` (for block device), `c` (character device), `d` (directory), `l` (symbolic + link), `p` (FIFO), `f` (regular file), and `s` (socket). +- `-links [-|+]number`: Checks if the file has the given number of hard links. +- `-user name`: Checks if the file is owned by the given user. Instead of a user + name, a numerical UID may be specified. +- `-group name`: Checks if the file is owned by the given group. Instead of a + group name, a numerical GID may be specified. +- `-size [-|+]number[bcwkMG]`: Checks if the file uses the specified `n` units of + space rounded up to the nearest whole unit. - The '+' and '-' prefixes denote greater than and less than, i.e an exact size - of `n` units doesn't match. Sizes are always rounded up to the nearest unit, - empty files, while the latter will match files from 0 to 1,048,575 bytes. - - The unit of space may be specified by any of these suffixes: + The '+' and '-' prefixes denote greater than and less than, i.e an exact size + of `n` units doesn't match. Sizes are always rounded up to the nearest unit, + empty files, while the latter will match files from 0 to 1,048,575 bytes. - * `b`: 512-byte blocks. This is the default unit if no suffix is used. - * `c`: bytes - * `w`: two-byte words - * `k`: kibibytes (1024 bytes) - * `M`: mebibytes (1024 kibibytes) - * `G`: gibibytes (1024 mebibytes) + The unit of space may be specified by any of these suffixes: -* `-path pattern`: Checks if the full file path matches the given global-style - pattern. This check matches against the full file name, starting from one of - the start points given on the command line. This means that using an absolute - path only makes sense in the case where the start point given on the command - line is an absolute path. For example, the following command will never match - anything: + - `b`: 512-byte blocks. This is the default unit if no suffix is used. + - `c`: bytes + - `w`: two-byte words + - `k`: kibibytes (1024 bytes) + - `M`: mebibytes (1024 kibibytes) + - `G`: gibibytes (1024 mebibytes) - `find bar -ipath '/foo/bar/test_file' -print` +- `-path pattern`: Checks if the full file path matches the given global-style + pattern. This check matches against the full file name, starting from one of + the start points given on the command line. This means that using an absolute + path only makes sense in the case where the start point given on the command + line is an absolute path. For example, the following command will never match + anything: - The given path is compared against the current directory concatenated with the - basename of the current file. Because such a concatenation can never end in a - '/', specifying path argument that ends with a '/' will never match anything. -* `-ipath pattern`: Functions identically to `-path` but is case-insensitive. -* `-name pattern`: Checks if the file name matches the given global-style - pattern (case sensitive). -* `-empty`: File is either an empty regular file or a directory containing no - files. -* `-iname pattern`: Checks if the file name matches the given global-style - pattern (case insensitive). -* `-readable`: Checks if the file is readable by the current user. -* `-writable`: Checks if the file is writable by the current user. -* `-executable`: Checks if the file is executable, or directory is searchable, -by the current user. -* `-newer file`: Checks if the file last modification time is greater than that - of the specified reference file. If `file` is a symbolic link and the `-L` - option is in use, then the last modification time of the file pointed to by - the symbolic link is used. -* `-anewer file`: Checks if the file last access time is greater than that of - the specified reference file. If `file` is a symbolic link and the `-L` - option is in use, then the last access time of the file pointed to by the - symbolic link is used. -* `-cnewer file`: Checks if the file creation time is greater than that of - the specified reference file. If `file` is a symbolic link and the `-L` - option is in use, then the creation time of the file pointed to by the - symbolic link is used. -* `-gid [-|+]number`: Checks if the file is owned by a group with an ID less - than, greater than or exactly `number`. -* `-uid [-|+]number`: Checks if the file is owned by a user with an ID less - than, greater than or exactly `number`. -* `-print`: Outputs the file path, followed by a newline. Always evaluates to - true. -* `-print0`: Outputs the file path, followed by a zero byte. Always evaluates to - true. -* `-exec command... ;`: Executes the given command with any arguments provided, - substituting the file path for any arguments specified as `{}`. The list of - arguments must be terminated by a semicolon. Checks if the command exits - successfully. -* `-ok command... ;`: Behaves identically to the `-exec` command, but will - prompt the user for confirmation before executing the given command. An - affirmative response is any response that begins with the 'y' character. - Any non-affirmative response will cause the command to not be executed and - the value returned by `-ok` to be false. + `find bar -ipath '/foo/bar/test_file' -print` + + The given path is compared against the current directory concatenated with the + basename of the current file. Because such a concatenation can never end in a + '/', specifying path argument that ends with a '/' will never match anything. + +- `-ipath pattern`: Functions identically to `-path` but is case-insensitive. +- `-name pattern`: Checks if the file name matches the given global-style + pattern (case sensitive). +- `-empty`: File is either an empty regular file or a directory containing no + files. +- `-iname pattern`: Checks if the file name matches the given global-style + pattern (case insensitive). +- `-readable`: Checks if the file is readable by the current user. +- `-writable`: Checks if the file is writable by the current user. +- `-executable`: Checks if the file is executable, or directory is searchable, + by the current user. +- `-newer file`: Checks if the file last modification time is greater than that + of the specified reference file. If `file` is a symbolic link and the `-L` + option is in use, then the last modification time of the file pointed to by + the symbolic link is used. +- `-anewer file`: Checks if the file last access time is greater than that of + the specified reference file. If `file` is a symbolic link and the `-L` + option is in use, then the last access time of the file pointed to by the + symbolic link is used. +- `-cnewer file`: Checks if the file creation time is greater than that of + the specified reference file. If `file` is a symbolic link and the `-L` + option is in use, then the creation time of the file pointed to by the + symbolic link is used. +- `-gid [-|+]number`: Checks if the file is owned by a group with an ID less + than, greater than or exactly `number`. +- `-uid [-|+]number`: Checks if the file is owned by a user with an ID less + than, greater than or exactly `number`. +- `-print`: Outputs the file path, followed by a newline. Always evaluates to + true. +- `-print0`: Outputs the file path, followed by a zero byte. Always evaluates to + true. +- `-exec command... ;`: Executes the given command with any arguments provided, + substituting the file path for any arguments specified as `{}`. The list of + arguments must be terminated by a semicolon. Checks if the command exits + successfully. +- `-ok command... ;`: Behaves identically to the `-exec` command, but will + prompt the user for confirmation before executing the given command. An + affirmative response is any response that begins with the 'y' character. + Any non-affirmative response will cause the command to not be executed and + the value returned by `-ok` to be false. The commands can be combined to form complex expressions using the following operators: -* `! command`: Logical NOT. -* `command1 -o command2`: Logical OR. -* `command1 -a command2`, `command1 command2`: Logical AND. -* `( command )`: Groups commands together for operator priority purposes. +- `! command`: Logical NOT. +- `command1 -o command2`: Logical OR. +- `command1 -a command2`, `command1 command2`: Logical AND. +- `( command )`: Groups commands together for operator priority purposes. Commands which take a numeric argument `n` (`-links` and `-size` for example), may be prefixed by a plus sign ('+') or a minus sign ('-'). A plus sign means @@ -137,4 +138,4 @@ $ find -name \*config\* ## See also -* [`xargs`(1)](help://man/1/xargs) +- [`xargs`(1)](help://man/1/xargs) diff --git a/Base/usr/share/man/man1/fortune.md b/Base/usr/share/man/man1/fortune.md index bf50aa49633..661b2f0345d 100644 --- a/Base/usr/share/man/man1/fortune.md +++ b/Base/usr/share/man/man1/fortune.md @@ -14,10 +14,10 @@ Open a fortune cookie, receive a free quote for the day! ## Options -* `--color when`: Chose when to color the output. Valid options are always, never and auto (default). When color is set to auto, color codes will be emitted when stdout is a terminal +- `--color when`: Chose when to color the output. Valid options are always, never and auto (default). When color is set to auto, color codes will be emitted when stdout is a terminal ## Arguments -* `path`: Path to JSON file with quotes (/res/fortunes.json by default) +- `path`: Path to JSON file with quotes (/res/fortunes.json by default) diff --git a/Base/usr/share/man/man1/gml-format.md b/Base/usr/share/man/man1/gml-format.md index 4eb084e4630..b92d0f04de3 100644 --- a/Base/usr/share/man/man1/gml-format.md +++ b/Base/usr/share/man/man1/gml-format.md @@ -14,7 +14,7 @@ $ gml-format [--inplace] [path...] ## Options -* `-i`, `--inplace`: Write formatted contents back to file rather than standard output +- `-i`, `--inplace`: Write formatted contents back to file rather than standard output ## Examples @@ -23,4 +23,5 @@ $ gml-format -i /home/anon/example.gml ``` ## See Also -* [`GML`(5)](help://man/5/GML) + +- [`GML`(5)](help://man/5/GML) diff --git a/Base/usr/share/man/man1/grep.md b/Base/usr/share/man/man1/grep.md index 2cff0400ccb..dc6c5c1e2f6 100644 --- a/Base/usr/share/man/man1/grep.md +++ b/Base/usr/share/man/man1/grep.md @@ -10,25 +10,25 @@ $ grep [--recursive] [--extended-regexp] [--fixed-strings] [--regexp Pattern] [- ## Options -* `-r`, `--recursive`: Recursively scan files -* `-E`, `--extended-regexp`: Extended regular expressions -* `-F`, `--fixed-strings`: Treat pattern as a string, not a regexp -* `-e Pattern`, `--regexp Pattern`: Pattern -* `-f File`, `--file File`: Read patterns from a file -* `-i`: Make matches case-insensitive -* `-n`, `--line-numbers`: Output line-numbers -* `-v`, `--invert-match`: Select non-matching lines -* `-q`, `--quiet`: Do not write anything to standard output -* `-s`, `--no-messages`: Suppress error messages for nonexistent or unreadable files -* `--binary-mode`: Action to take for binary files ([binary], text, skip) -* `-a`, `--text`: Treat binary files as text (same as --binary-mode text) -* `-I`: Ignore binary files (same as --binary-mode skip) -* `--color WHEN`: When to use colored output for the matching text ([auto], never, always) -* `--no-hyperlinks`: Disable hyperlinks -* `-c`, `--count`: Output line count instead of line contents +- `-r`, `--recursive`: Recursively scan files +- `-E`, `--extended-regexp`: Extended regular expressions +- `-F`, `--fixed-strings`: Treat pattern as a string, not a regexp +- `-e Pattern`, `--regexp Pattern`: Pattern +- `-f File`, `--file File`: Read patterns from a file +- `-i`: Make matches case-insensitive +- `-n`, `--line-numbers`: Output line-numbers +- `-v`, `--invert-match`: Select non-matching lines +- `-q`, `--quiet`: Do not write anything to standard output +- `-s`, `--no-messages`: Suppress error messages for nonexistent or unreadable files +- `--binary-mode`: Action to take for binary files ([binary], text, skip) +- `-a`, `--text`: Treat binary files as text (same as --binary-mode text) +- `-I`: Ignore binary files (same as --binary-mode skip) +- `--color WHEN`: When to use colored output for the matching text ([auto], never, always) +- `--no-hyperlinks`: Disable hyperlinks +- `-c`, `--count`: Output line count instead of line contents ## Arguments -* `file`: File(s) to process +- `file`: File(s) to process diff --git a/Base/usr/share/man/man1/groups.md b/Base/usr/share/man/man1/groups.md index ce093f77f29..4a1755d719c 100644 --- a/Base/usr/share/man/man1/groups.md +++ b/Base/usr/share/man/man1/groups.md @@ -16,7 +16,7 @@ If no username is provided group memberships are listed for current user. ## Arguments -* `username`: username to list group memberships for +- `username`: username to list group memberships for ## Examples @@ -30,5 +30,6 @@ $ groups nona anon root ``` ## See Also -* [`groupdel`(8)](help://man/8/groupdel) -* [`groupadd`(8)](help://man/8/groupadd) + +- [`groupdel`(8)](help://man/8/groupdel) +- [`groupadd`(8)](help://man/8/groupadd) diff --git a/Base/usr/share/man/man1/gzip.md b/Base/usr/share/man/man1/gzip.md index d4a3745925b..76aa02fff80 100644 --- a/Base/usr/share/man/man1/gzip.md +++ b/Base/usr/share/man/man1/gzip.md @@ -12,13 +12,14 @@ $ zcat ## Options -* `-k`, `--keep`: Keep (don't delete) input files -* `-c`, `--stdout`: Write to stdout, keep original files unchanged -* `-d`, `--decompress`: Decompress +- `-k`, `--keep`: Keep (don't delete) input files +- `-c`, `--stdout`: Write to stdout, keep original files unchanged +- `-d`, `--decompress`: Decompress ## Arguments -* `FILES`: Files +- `FILES`: Files ## See also -* [`tar`(1)](help://man/1/tar) + +- [`tar`(1)](help://man/1/tar) diff --git a/Base/usr/share/man/man1/head.md b/Base/usr/share/man/man1/head.md index 0daa38f7042..4ddb5722846 100644 --- a/Base/usr/share/man/man1/head.md +++ b/Base/usr/share/man/man1/head.md @@ -10,22 +10,21 @@ $ head [option...] [file...] ## Description -Print the first 10 lines of each `file` to standard output. With more than one `file`, +Print the first 10 lines of each `file` to standard output. With more than one `file`, precede each with a header giving the file name. With no `file`, or when `file` is `-`, read standard input. ## Arguments -* `file`: File to process +- `file`: File to process ## Options -* `-n` `--number=NUM`: Number of lines to print (default 10) -* `-c` `--bytes=NUM`: Number of bytes to print -* `-q` `--quiet`: Never print filenames -* `-v` `--verbose`: Always print filenames - +- `-n` `--number=NUM`: Number of lines to print (default 10) +- `-c` `--bytes=NUM`: Number of bytes to print +- `-q` `--quiet`: Never print filenames +- `-v` `--verbose`: Always print filenames ## Examples @@ -40,5 +39,6 @@ Graphical Unix-like operating system for x86 computers. ``` ## See also -* [`tail`(1)](help://man/1/tail) -* [`cat`(1)](help://man/1/cat) + +- [`tail`(1)](help://man/1/tail) +- [`cat`(1)](help://man/1/cat) diff --git a/Base/usr/share/man/man1/id.md b/Base/usr/share/man/man1/id.md index f15221f4cda..8a6a4c6ed46 100644 --- a/Base/usr/share/man/man1/id.md +++ b/Base/usr/share/man/man1/id.md @@ -14,10 +14,10 @@ $ id [options...] ## 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. +- `-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 @@ -36,6 +36,6 @@ $ id -G ## See also -* [`whoami`(1)](help://man/1/whoami) -* [`groups`(1)](help://man/1/groups) -* [`usermod`(8)](help://man/8/usermod) +- [`whoami`(1)](help://man/1/whoami) +- [`groups`(1)](help://man/1/groups) +- [`usermod`(8)](help://man/8/usermod) diff --git a/Base/usr/share/man/man1/ifconfig.md b/Base/usr/share/man/man1/ifconfig.md index c8f9da6f5f5..652ce37d0c5 100644 --- a/Base/usr/share/man/man1/ifconfig.md +++ b/Base/usr/share/man/man1/ifconfig.md @@ -14,12 +14,13 @@ Display or modify the configuration of each network interface. ## Options -* `-i ip`, `--ipv4 ip`: Set the IP address of the selected network -* `-a adapter`, `--adapter adapter`: Select a specific network adapter to configure -* `-m mask`, `--mask mask`: Set the network mask of the selected network +- `-i ip`, `--ipv4 ip`: Set the IP address of the selected network +- `-a adapter`, `--adapter adapter`: Select a specific network adapter to configure +- `-m mask`, `--mask mask`: Set the network mask of the selected network ## See Also -* [`Network`(5)](help://man/5/Network) -* [`netstat`(1)](help://man/1/netstat) + +- [`Network`(5)](help://man/5/Network) +- [`netstat`(1)](help://man/1/netstat) diff --git a/Base/usr/share/man/man1/js.md b/Base/usr/share/man/man1/js.md index 5b8754cd33b..0c9cc8d0b6d 100644 --- a/Base/usr/share/man/man1/js.md +++ b/Base/usr/share/man/man1/js.md @@ -21,17 +21,17 @@ Run `help()` in REPL mode to see its available built-in functions. ## Options -* `-A`, `--dump-ast`: Dump the Abstract Syntax Tree after parsing the program. -* `-d`, `--dump-bytecode`: Dump the bytecode -* `-b`, `--run-bytecode`: Run the bytecode -* `-p`, `--optimize-bytecode`: Optimize the bytecode -* `-m`, `--as-module`: Treat as module -* `-l`, `--print-last-result`: Print the result of the last statement executed. -* `-g`, `--gc-on-every-allocation`: Run garbage collection on every allocation. -* `-i`, `--disable-ansi-colors`: Disable ANSI colors -* `-h`, `--disable-source-location-hints`: Disable source location hints -* `-s`, `--no-syntax-highlight`: Disable live syntax highlighting in the REPL -* `-c`, `--evaluate`: Evaluate the argument as a script +- `-A`, `--dump-ast`: Dump the Abstract Syntax Tree after parsing the program. +- `-d`, `--dump-bytecode`: Dump the bytecode +- `-b`, `--run-bytecode`: Run the bytecode +- `-p`, `--optimize-bytecode`: Optimize the bytecode +- `-m`, `--as-module`: Treat as module +- `-l`, `--print-last-result`: Print the result of the last statement executed. +- `-g`, `--gc-on-every-allocation`: Run garbage collection on every allocation. +- `-i`, `--disable-ansi-colors`: Disable ANSI colors +- `-h`, `--disable-source-location-hints`: Disable source location hints +- `-s`, `--no-syntax-highlight`: Disable live syntax highlighting in the REPL +- `-c`, `--evaluate`: Evaluate the argument as a script ## Examples @@ -63,4 +63,4 @@ undefined ## See also -* [`test-js`(1)](help://man/1/test-js) +- [`test-js`(1)](help://man/1/test-js) diff --git a/Base/usr/share/man/man1/json.md b/Base/usr/share/man/man1/json.md index 2f38291c201..60e825f5317 100644 --- a/Base/usr/share/man/man1/json.md +++ b/Base/usr/share/man/man1/json.md @@ -12,17 +12,17 @@ $ json [options...] [path...] `json` pretty-prints a JSON file with syntax-coloring and indentation. -If no *path* argument is provided stdin is used. +If no _path_ argument is provided stdin is used. ## Options -* `--help`: Display this message -* `-i`, `--indent-size`: Size of indentations in spaces -* `-q`, `--query`: Dotted query key +- `--help`: Display this message +- `-i`, `--indent-size`: Size of indentations in spaces +- `-q`, `--query`: Dotted query key ## Arguments -* `path`: file to pretty-print +- `path`: file to pretty-print ## Examples diff --git a/Base/usr/share/man/man1/keymap.md b/Base/usr/share/man/man1/keymap.md index 838f5abc8d7..a72351e602e 100644 --- a/Base/usr/share/man/man1/keymap.md +++ b/Base/usr/share/man/man1/keymap.md @@ -16,23 +16,26 @@ Layouts loaded from `/res/keymaps/*.json`. ## Options -* `-m keymap`, `--set-keymap keymap`: The mapping to be used -* `-s keymaps`, `--set-keymaps keymaps`: Comma separated list of enabled mappings +- `-m keymap`, `--set-keymap keymap`: The mapping to be used +- `-s keymaps`, `--set-keymaps keymaps`: Comma separated list of enabled mappings ## Examples Get name of the currently set keymap: + ```sh $ keymap en-us ``` Select a new list of keymaps: + ```sh $ keymap --set-keymaps en-us,ru ``` Set a keymap: + ```sh $ keymap --set-keymap ru ``` diff --git a/Base/usr/share/man/man1/less.md b/Base/usr/share/man/man1/less.md index fa2afcd8c7c..b256d348e41 100644 --- a/Base/usr/share/man/man1/less.md +++ b/Base/usr/share/man/man1/less.md @@ -19,26 +19,26 @@ but largely incompatible with ## Options -* `-P`, `--prompt`: Set the prompt format string. See [Prompts](#prompts) for more details. -* `-X`, `--no-init`: Don't switch to the xterm alternate buffer on startup. -* `-N`, `--line-numbers`: Show line numbers before printed lines. -* `-e`, `--quit-at-eof`: Immediately exit less when the last line of the document is reached. -* `-F`, `--quit-if-one-screen`: Exit immediately if the entire file can be displayed on one screen. -* `-m`, `--emulate-more`: Apply `-Xe`, set the prompt to `--More--`, and disable - scrollback. This option is automatically applied when `less` is executed as `more` +- `-P`, `--prompt`: Set the prompt format string. See [Prompts](#prompts) for more details. +- `-X`, `--no-init`: Don't switch to the xterm alternate buffer on startup. +- `-N`, `--line-numbers`: Show line numbers before printed lines. +- `-e`, `--quit-at-eof`: Immediately exit less when the last line of the document is reached. +- `-F`, `--quit-if-one-screen`: Exit immediately if the entire file can be displayed on one screen. +- `-m`, `--emulate-more`: Apply `-Xe`, set the prompt to `--More--`, and disable + scrollback. This option is automatically applied when `less` is executed as `more` ## Commands Commands may be preceded by a decimal number `N`. Currently, this feature does not exist, and no command use `N`. -| Command | Description | -|---------|-------------| -| `q` | Exit less. | -| `j` or `DOWNARROW` or `ENTER` | Go to the next line. | -| `k` or `UPARROW` | Go to the previous line. | -| `f` or `SPACE` | Go to the next page. | -| `b` | Go to the previous page. | +| Command | Description | +| ----------------------------- | ------------------------ | +| `q` | Exit less. | +| `j` or `DOWNARROW` or `ENTER` | Go to the next line. | +| `k` or `UPARROW` | Go to the previous line. | +| `f` or `SPACE` | Go to the next page. | +| `b` | Go to the previous page. | ## Prompts @@ -49,10 +49,10 @@ A `%` followed by a letter will be replaced with the associated variable. If such a variable does not exist, or currently has no value, it will be replaced with a `?`. -| Variable | Description | -|----------|-------------| -| `%f` | Replaced with the name of the current file | -| `%l` | Replaced with the current line number | +| Variable | Description | +| -------- | ------------------------------------------ | +| `%f` | Replaced with the name of the current file | +| `%l` | Replaced with the current line number | A `?` followed by a letter acts as an if expression on the associated condition. `:` then acts as the else, and `.` acts as the end token. for example @@ -61,10 +61,10 @@ otherwise, your prompt would be `?etrue:false.`. These expressions are arbitrarily nestable. If a condition does not exist, then it will always evaluate it's false branch. -| Condition | Description | -|----------|-------------| -| `?f` | True when reading from a file other than stdin. | -| `?e` | True when at the end of a file. | +| Condition | Description | +| --------- | ----------------------------------------------- | +| `?f` | True when reading from a file other than stdin. | +| `?e` | True when at the end of a file. | A `\\` followed by any character will be replaced with the literal value of the character. For instance, `\\%l` would render as `%l`. @@ -77,5 +77,5 @@ All other characters are treated normally. ## See Also -* [`more`(1)](help://man/1/more) For a simpler pager that less implements. -* [`man`(1)](help://man/1/man) For serenity's manual pager, that uses less. +- [`more`(1)](help://man/1/more) For a simpler pager that less implements. +- [`man`(1)](help://man/1/man) For serenity's manual pager, that uses less. diff --git a/Base/usr/share/man/man1/listdir.md b/Base/usr/share/man/man1/listdir.md index bb63324537a..5454f78788d 100644 --- a/Base/usr/share/man/man1/listdir.md +++ b/Base/usr/share/man/man1/listdir.md @@ -11,7 +11,7 @@ lsdir - list directory entries ## Description This utility will list all directory entries of a given path (or list of paths) -and print their inode number and file type (in either POSIX DT_* format or human readable). +and print their inode number and file type (in either POSIX DT\_\* format or human readable). The utility uses `LibCore` `DirIterator` object and restrict its functionality to the `get_dir_entries` syscall only, to get the raw values of each directory @@ -19,19 +19,19 @@ entry. ## Options -* `-P`, `--posix-names`: Show POSIX names for file types -* `-t`, `--total-entries-count`: Print count of listed entries when traversing a directory +- `-P`, `--posix-names`: Show POSIX names for file types +- `-t`, `--total-entries-count`: Print count of listed entries when traversing a directory ## Arguments -* `path`: Directory to list +- `path`: Directory to list ## Examples ```sh # List directory entries of working directory $ lsdir -# List directory entries of /proc directory +# List directory entries of /proc directory $ lsdir /proc # List directory entries of /proc directory with POSIX names for file types $ lsdir -P /proc @@ -40,4 +40,5 @@ $ lsdir -t /proc ``` ## See also -* [`ls`(1)](help://man/1/ls) + +- [`ls`(1)](help://man/1/ls) diff --git a/Base/usr/share/man/man1/ls.md b/Base/usr/share/man/man1/ls.md index e2873d2d283..b94456fbcc3 100644 --- a/Base/usr/share/man/man1/ls.md +++ b/Base/usr/share/man/man1/ls.md @@ -12,36 +12,36 @@ $ ls [options...] [path...] `ls` lists directory contents and attributes. -If no *path* argument is provided the current working directory is used. +If no _path_ argument is provided the current working directory is used. ## Options -* `--help`: Display this message -* `-a`, `--all`: Show dotfiles -* `-A`: Do not list implied . and .. directories -* `-B`, `--ignore-backups`: Do not list implied entries ending with ~ -* `-F`, `--classify`: Append a file type indicator to entries -* `-p`: Append a '/' indicator to directories -* `-d`, `--directory`: List directories themselves, not their contents -* `-l`, `--long`: Display long info -* `-t`: Sort files by timestamp (newest first) -* `-S`: Sort files by size (largest first) -* `-r`, `--reverse`: Reverse sort order -* `-G`: Use pretty colors -* `-i`, `--inode`: Show inode ids -* `-I`, `--raw-inode`: Show raw inode ids if possible (see Notes to understand when this will not work) -* `-n`, `--numeric-uid-gid`: In long format, display numeric UID/GID. Implies `-l` -* `-o`: In long format, do not show group information. Implies `-l` -* `-g`: In long format, do not show owner information. Implies `-l` -* `-h`, `--human-readable`: Print human-readable sizes -* `--si`: Print human-readable sizes in SI units -* `-K`, `--no-hyperlinks`: Disable hyperlinks -* `-R`, `--recursive`: List subdirectories recursively -* `-1`: List one file per line +- `--help`: Display this message +- `-a`, `--all`: Show dotfiles +- `-A`: Do not list implied . and .. directories +- `-B`, `--ignore-backups`: Do not list implied entries ending with ~ +- `-F`, `--classify`: Append a file type indicator to entries +- `-p`: Append a '/' indicator to directories +- `-d`, `--directory`: List directories themselves, not their contents +- `-l`, `--long`: Display long info +- `-t`: Sort files by timestamp (newest first) +- `-S`: Sort files by size (largest first) +- `-r`, `--reverse`: Reverse sort order +- `-G`: Use pretty colors +- `-i`, `--inode`: Show inode ids +- `-I`, `--raw-inode`: Show raw inode ids if possible (see Notes to understand when this will not work) +- `-n`, `--numeric-uid-gid`: In long format, display numeric UID/GID. Implies `-l` +- `-o`: In long format, do not show group information. Implies `-l` +- `-g`: In long format, do not show owner information. Implies `-l` +- `-h`, `--human-readable`: Print human-readable sizes +- `--si`: Print human-readable sizes in SI units +- `-K`, `--no-hyperlinks`: Disable hyperlinks +- `-R`, `--recursive`: List subdirectories recursively +- `-1`: List one file per line ## Arguments -* `path`: Directory to list +- `path`: Directory to list ## Examples @@ -69,4 +69,5 @@ is a mounted filesystem on a directory entry, `lstat` will give the root inode number for that filesystem. ## See also -* [`tree`(1)](help://man/1/tree) to show the contents of the directory and subdirectories in a tree visualization + +- [`tree`(1)](help://man/1/tree) to show the contents of the directory and subdirectories in a tree visualization diff --git a/Base/usr/share/man/man1/lsof.md b/Base/usr/share/man/man1/lsof.md index 6d6691679db..8c8d57a056e 100644 --- a/Base/usr/share/man/man1/lsof.md +++ b/Base/usr/share/man/man1/lsof.md @@ -14,15 +14,16 @@ List open files of a processes. This can mean actual files in the file system, s ## Options -* `-p pid`: Select by PID -* `-d fd`: Select by file descriptor -* `-u login/UID`: Select by login/UID -* `-g PGID`: Select by process group ID +- `-p pid`: Select by PID +- `-d fd`: Select by file descriptor +- `-u login/UID`: Select by login/UID +- `-g PGID`: Select by process group ID ## Arguments -* `filename`: Filename +- `filename`: Filename ## See Also -* [`pmap`(1)](help://man/1/pmap) -* [`ps`(1)](help://man/1/ps) + +- [`pmap`(1)](help://man/1/pmap) +- [`ps`(1)](help://man/1/ps) diff --git a/Base/usr/share/man/man1/man.md b/Base/usr/share/man/man1/man.md index fd6d54bdc7b..c5d1bee731f 100644 --- a/Base/usr/share/man/man1/man.md +++ b/Base/usr/share/man/man1/man.md @@ -17,20 +17,24 @@ the manual page for `man` program itself right now. ## Options -* `-P pager`, `--pager pager`: Pager to pipe the man page to +- `-P pager`, `--pager pager`: Pager to pipe the man page to ## 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 ``` @@ -42,6 +46,6 @@ this man page should be located at `/usr/share/man/man1/man.md`. ## See Also -* [`less`(1)](help://man/1/less) For the terminal pager that `man` uses by default -* [`Help`(1)](help://man/1/Applications/Help) To read these same man pages in a GUI -* [`man`(7)](help://man/7/man) For an overview on how manpages are organized +- [`less`(1)](help://man/1/less) For the terminal pager that `man` uses by default +- [`Help`(1)](help://man/1/Applications/Help) To read these same man pages in a GUI +- [`man`(7)](help://man/7/man) For an overview on how manpages are organized diff --git a/Base/usr/share/man/man1/md.md b/Base/usr/share/man/man1/md.md index b06509bf667..878aa11b0ed 100644 --- a/Base/usr/share/man/man1/md.md +++ b/Base/usr/share/man/man1/md.md @@ -17,7 +17,7 @@ standard input. ## Options -* `-H`, `--html`: Render the document into HTML. +- `-H`, `--html`: Render the document into HTML. ## Examples @@ -28,4 +28,5 @@ $ md --html /usr/share/man/man1/md.md ``` ## See Also -* [`man`(1)](help://man/1/man) to more easily read manpages + +- [`man`(1)](help://man/1/man) to more easily read manpages diff --git a/Base/usr/share/man/man1/memstat.md b/Base/usr/share/man/man1/memstat.md index 1e930195a50..fef2e165935 100644 --- a/Base/usr/share/man/man1/memstat.md +++ b/Base/usr/share/man/man1/memstat.md @@ -10,7 +10,7 @@ $ memstat ## Options -* `-h` , `--human-readable`: Print human-readable sizes +- `-h` , `--human-readable`: Print human-readable sizes ## Examples diff --git a/Base/usr/share/man/man1/mkdir.md b/Base/usr/share/man/man1/mkdir.md index fbb31e16fcb..55dfbd3631a 100644 --- a/Base/usr/share/man/man1/mkdir.md +++ b/Base/usr/share/man/man1/mkdir.md @@ -10,14 +10,14 @@ $ mkdir [options...] directories... ## Description -Create a new empty directory for each of the given *directories*. +Create a new empty directory for each of the given _directories_. ## Options -* `-p`, `--parents`: Create parent directories if they don't exist -* `-m`, `--mode`: Sets the permissions for the final directory (possibly altered by the process umask). The mode argument can be given in any of the formats -accepted by the chmod(1) command. Addition and removal of permissions is relative to a default permission of 0777. -* `-v`, `--verbose`: Print a message for each created directory +- `-p`, `--parents`: Create parent directories if they don't exist +- `-m`, `--mode`: Sets the permissions for the final directory (possibly altered by the process umask). The mode argument can be given in any of the formats + accepted by the chmod(1) command. Addition and removal of permissions is relative to a default permission of 0777. +- `-v`, `--verbose`: Print a message for each created directory ## Examples @@ -29,4 +29,4 @@ $ mkdir -m a=rx /tmp/foo/bar ## See also -* [`mkdir`(2)](help://man/2/mkdir) +- [`mkdir`(2)](help://man/2/mkdir) diff --git a/Base/usr/share/man/man1/mktemp.md b/Base/usr/share/man/man1/mktemp.md index 016ad7e46a9..3d0ea708989 100644 --- a/Base/usr/share/man/man1/mktemp.md +++ b/Base/usr/share/man/man1/mktemp.md @@ -17,10 +17,10 @@ as long as it contains at least 3 consecutive 'X's. ## Options -* `-d`, `--directory`: Create a temporary directory instead of a file -* `-u`, `--dry-run`: Do not create anything, just print a unique name -* `-q`, `--quiet`: Do not print diagnostics about file/directory creation failure -* `-p`, `--tmpdir`: Create temporary files relative to this directory +- `-d`, `--directory`: Create a temporary directory instead of a file +- `-u`, `--dry-run`: Do not create anything, just print a unique name +- `-q`, `--quiet`: Do not print diagnostics about file/directory creation failure +- `-p`, `--tmpdir`: Create temporary files relative to this directory ## Examples @@ -34,5 +34,6 @@ $ mktemp -d serenity.XXXXX ``` ## See also -* [`mkdir`(1)](help://man/1/mkdir) to create a regular directory -* [`touch`(1)](help://man/1/touch) to create a regular file + +- [`mkdir`(1)](help://man/1/mkdir) to create a regular directory +- [`touch`(1)](help://man/1/touch) to create a regular file diff --git a/Base/usr/share/man/man1/more.md b/Base/usr/share/man/man1/more.md index d8267345f96..67e2911ac78 100644 --- a/Base/usr/share/man/man1/more.md +++ b/Base/usr/share/man/man1/more.md @@ -23,4 +23,4 @@ $ more ## See Also -* [`less`(1)](help://man/1/less) For the more advanced terminal pager that implements more. +- [`less`(1)](help://man/1/less) For the more advanced terminal pager that implements more. diff --git a/Base/usr/share/man/man1/mv.md b/Base/usr/share/man/man1/mv.md index d753a477676..fa46df79a9d 100644 --- a/Base/usr/share/man/man1/mv.md +++ b/Base/usr/share/man/man1/mv.md @@ -15,9 +15,9 @@ $ mv [options...] ## Options -* `-f`, `--force`: Do not prompt before overwriting (not implemented for now) -* `-n`, `--no-clobber`: Do not overwrite existing files -* `-v`, `--verbose`: Display all moved files +- `-f`, `--force`: Do not prompt before overwriting (not implemented for now) +- `-n`, `--no-clobber`: Do not overwrite existing files +- `-v`, `--verbose`: Display all moved files ## Examples @@ -28,4 +28,5 @@ $ mv old.txt new.txt ``` ## See also -* [`cp`(1)](help://man/1/cp) + +- [`cp`(1)](help://man/1/cp) diff --git a/Base/usr/share/man/man1/nc.md b/Base/usr/share/man/man1/nc.md index 816cf6f36c2..258550fd434 100644 --- a/Base/usr/share/man/man1/nc.md +++ b/Base/usr/share/man/man1/nc.md @@ -14,18 +14,18 @@ Network cat: Connect to network sockets as if it were a file. ## Options -* `-I`, `--length`: Set maximum tcp receive buffer size -* `-l`, `--listen`: Listen instead of connecting -* `-N`: Close connection after reading stdin to the end -* `-n`: Suppress name resolution -* `-u`, `--udp`: UDP mode -* `-p port`: Local port for remote connections -* `-v`, `--verbose`: Log everything that's happening -* `-z`, `--test-listening-service`: Test a TCP-listening service +- `-I`, `--length`: Set maximum tcp receive buffer size +- `-l`, `--listen`: Listen instead of connecting +- `-N`: Close connection after reading stdin to the end +- `-n`: Suppress name resolution +- `-u`, `--udp`: UDP mode +- `-p port`: Local port for remote connections +- `-v`, `--verbose`: Log everything that's happening +- `-z`, `--test-listening-service`: Test a TCP-listening service ## Arguments -* `target`: Address to listen on, or the address or hostname to connect to -* `port`: Port to connect to or listen on +- `target`: Address to listen on, or the address or hostname to connect to +- `port`: Port to connect to or listen on diff --git a/Base/usr/share/man/man1/netstat.md b/Base/usr/share/man/man1/netstat.md index 730edeb79c2..6746b04d87c 100644 --- a/Base/usr/share/man/man1/netstat.md +++ b/Base/usr/share/man/man1/netstat.md @@ -14,14 +14,15 @@ Display network connections ## Options -* `-a`, `--all`: Display both listening and non-listening sockets -* `-l`, `--list`: Display only listening sockets -* `-t`, `--tcp`: Display only TCP network connections -* `-u`, `--udp`: Display only UDP network connections -* `-n`, `--numeric`: Display numerical addresses -* `-p`, `--program`: Show the PID and name of the program to which each socket belongs -* `-W`, `--wide`: Do not truncate IP addresses by printing out the whole symbolic host -* `-e`, `--extend`: Display more information +- `-a`, `--all`: Display both listening and non-listening sockets +- `-l`, `--list`: Display only listening sockets +- `-t`, `--tcp`: Display only TCP network connections +- `-u`, `--udp`: Display only UDP network connections +- `-n`, `--numeric`: Display numerical addresses +- `-p`, `--program`: Show the PID and name of the program to which each socket belongs +- `-W`, `--wide`: Do not truncate IP addresses by printing out the whole symbolic host +- `-e`, `--extend`: Display more information ## See Also -* [`ifconfig`(1)](help://man/1/ifconfig) + +- [`ifconfig`(1)](help://man/1/ifconfig) diff --git a/Base/usr/share/man/man1/nl.md b/Base/usr/share/man/man1/nl.md index 7e2d4476256..390ab441555 100644 --- a/Base/usr/share/man/man1/nl.md +++ b/Base/usr/share/man/man1/nl.md @@ -10,14 +10,14 @@ $ nl [--body-numbering style] [--increment number] [--separator string] [--start ## Options -* `-b style`, `--body-numbering style`: Line numbering style: 't' for non-empty lines, 'a' for all lines, 'n' for no lines -* `-i number`, `--increment number`: Line count increment -* `-s string`, `--separator string`: Separator between line numbers and lines -* `-v number`, `--startnum number`: Initial line number -* `-w number`, `--width number`: Number width +- `-b style`, `--body-numbering style`: Line numbering style: 't' for non-empty lines, 'a' for all lines, 'n' for no lines +- `-i number`, `--increment number`: Line count increment +- `-s string`, `--separator string`: Separator between line numbers and lines +- `-v number`, `--startnum number`: Initial line number +- `-w number`, `--width number`: Number width ## Arguments -* `file`: Files to process +- `file`: Files to process diff --git a/Base/usr/share/man/man1/nohup.md b/Base/usr/share/man/man1/nohup.md index 5a7d85bafd3..ba37a5389fd 100644 --- a/Base/usr/share/man/man1/nohup.md +++ b/Base/usr/share/man/man1/nohup.md @@ -9,6 +9,7 @@ $ nohup [args...] ``` ## Description + `nohup` will invoke `utility` given an optional list of `args`, where at the time of the invocation it will ignore the SIGHUP signal. If the standard output is a tty, `utility` will append its standard output to the end of the file **nohup.out** in the current directory. If **nohup.out** fails to be created or opened for @@ -16,15 +17,16 @@ appending, `utility`'s standard output will instead be appended to the end of th permission bits are set to S_IRUSR | S_IWUSR when it is created. If standard error is a tty, one out of the following will occur: + 1. If the standard output is open but not a tty, `utility` will redirect its standard error to its standard output. 2. If the standard output is a tty or is closed, standard error shall be appended to the end of **nohup.out** as described above. ## Arguments -* `utility`: Utility to be invoked -* `args`: Arguments to pass to `utility` +- `utility`: Utility to be invoked +- `args`: Arguments to pass to `utility` ## Exit Status -* 126 - `utility` was found but could not be invoked. -* 127 - Either `utility` could not be found or an error occurred in `nohup`. +- 126 - `utility` was found but could not be invoked. +- 127 - Either `utility` could not be found or an error occurred in `nohup`. diff --git a/Base/usr/share/man/man1/notify.md b/Base/usr/share/man/man1/notify.md index 772d875a2b0..bdf8a025a72 100644 --- a/Base/usr/share/man/man1/notify.md +++ b/Base/usr/share/man/man1/notify.md @@ -10,9 +10,9 @@ $ notify <message> [icon-path] ## Arguments -* `title`: The title of notification -* `message`: The message of notification -* `icon-path`: Path to icon image file +- `title`: The title of notification +- `message`: The message of notification +- `icon-path`: Path to icon image file ## Description diff --git a/Base/usr/share/man/man1/ntpquery.md b/Base/usr/share/man/man1/ntpquery.md index 51f07a3019c..264805f31f2 100644 --- a/Base/usr/share/man/man1/ntpquery.md +++ b/Base/usr/share/man/man1/ntpquery.md @@ -10,13 +10,14 @@ $ ntpquery [--adjust] [--set] [--verbose] [host] ## Options -* `-a`, `--adjust`: Gradually adjust system time (requires root) -* `-s`, `--set`: Immediately set system time (requires root) -* `-v`, `--verbose`: Verbose output +- `-a`, `--adjust`: Gradually adjust system time (requires root) +- `-s`, `--set`: Immediately set system time (requires root) +- `-v`, `--verbose`: Verbose output ## Arguments -* `host`: NTP server +- `host`: NTP server ## See Also -* [`date`(1)](help://man/1/date) + +- [`date`(1)](help://man/1/date) diff --git a/Base/usr/share/man/man1/passwd.md b/Base/usr/share/man/man1/passwd.md index 7932cdc3287..cdda705db9b 100644 --- a/Base/usr/share/man/man1/passwd.md +++ b/Base/usr/share/man/man1/passwd.md @@ -14,12 +14,12 @@ Modify an account password. ## Options -* `-d`, `--delete`: Delete password -* `-l`, `--lock`: Lock password -* `-u`, `--unlock`: Unlock password +- `-d`, `--delete`: Delete password +- `-l`, `--lock`: Lock password +- `-u`, `--unlock`: Unlock password ## Arguments -* `username`: Username +- `username`: Username <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man1/pgrep.md b/Base/usr/share/man/man1/pgrep.md index ba0df8c1d3c..39de031403f 100644 --- a/Base/usr/share/man/man1/pgrep.md +++ b/Base/usr/share/man/man1/pgrep.md @@ -10,21 +10,22 @@ $ pgrep [--count] [-d delimiter] [--ignore-case] [--list-name] [--newest] [--old ## Options -* `-c`, `--count`: Suppress normal output and print the number of matching processes -* `-d`, `--delimiter`: Set the string used to delimit multiple pids -* `-i`, `--ignore-case`: Make matches case-insensitive -* `-l`, `--list-name`: List the process name in addition to its pid -* `-n`, `--newest`: Select the most recently created process only -* `-o`, `--oldest`: Select the least recently created process only -* `-O`, `--older`: Select only processes older than the specified number of seconds -* `-U uid-list`, `--uid uid-list`: Select only processes whose UID is in the given comma-separated list. Login name or numerical user ID may be used -* `-x`, `--exact`: Select only processes whose names match the given pattern exactly -* `-v`, `--invert-match`: Select non-matching lines +- `-c`, `--count`: Suppress normal output and print the number of matching processes +- `-d`, `--delimiter`: Set the string used to delimit multiple pids +- `-i`, `--ignore-case`: Make matches case-insensitive +- `-l`, `--list-name`: List the process name in addition to its pid +- `-n`, `--newest`: Select the most recently created process only +- `-o`, `--oldest`: Select the least recently created process only +- `-O`, `--older`: Select only processes older than the specified number of seconds +- `-U uid-list`, `--uid uid-list`: Select only processes whose UID is in the given comma-separated list. Login name or numerical user ID may be used +- `-x`, `--exact`: Select only processes whose names match the given pattern exactly +- `-v`, `--invert-match`: Select non-matching lines ## Arguments -* `process-name`: Process name to search for +- `process-name`: Process name to search for ## See also -* [`pidof`(1)](help://man/1/pidof) -* [`ps`(1)](help://man/1/ps) + +- [`pidof`(1)](help://man/1/pidof) +- [`ps`(1)](help://man/1/ps) diff --git a/Base/usr/share/man/man1/pidof.md b/Base/usr/share/man/man1/pidof.md index 42da018a635..40b50b8d954 100644 --- a/Base/usr/share/man/man1/pidof.md +++ b/Base/usr/share/man/man1/pidof.md @@ -10,14 +10,15 @@ $ pidof [-s] [-o pid] [-S separator] <process-name> ## Options -* `-o pid`: Omit the given pid, or the parent process if the special value %PPID is passed -* `-s`: Only return one pid -* `-S separator`: Use `separator` to separate multiple pids +- `-o pid`: Omit the given pid, or the parent process if the special value %PPID is passed +- `-s`: Only return one pid +- `-S separator`: Use `separator` to separate multiple pids ## Arguments -* `process-name`: Process name to search for +- `process-name`: Process name to search for ## See also -* [`pgrep`(1)](help://man/1/pgrep) -* [`ps`(1)](help://man/1/ps) + +- [`pgrep`(1)](help://man/1/pgrep) +- [`ps`(1)](help://man/1/ps) diff --git a/Base/usr/share/man/man1/pkg.md b/Base/usr/share/man/man1/pkg.md index 7a01fe7a70f..0f93444c9ec 100644 --- a/Base/usr/share/man/man1/pkg.md +++ b/Base/usr/share/man/man1/pkg.md @@ -16,14 +16,14 @@ It does not currently support installing and uninstalling packages. To install t ## Options -* `-l`, `--list-manual-ports`: Show all manually-installed ports -* `-u`, `--update-ports-database`: Sync/Update ports database -* `-v`, `--verbose`: Verbose output -* `-q`, `--query-package`: Query the ports database for package name +- `-l`, `--list-manual-ports`: Show all manually-installed ports +- `-u`, `--update-ports-database`: Sync/Update ports database +- `-v`, `--verbose`: Verbose output +- `-q`, `--query-package`: Query the ports database for package name ## Arguments -* `package`: The name of the package you want to query +- `package`: The name of the package you want to query ## Example diff --git a/Base/usr/share/man/man1/pkill.md b/Base/usr/share/man/man1/pkill.md index cddb9f79b4e..6a5b33fcbba 100644 --- a/Base/usr/share/man/man1/pkill.md +++ b/Base/usr/share/man/man1/pkill.md @@ -10,19 +10,20 @@ $ pkill [--count] [--ignore-case] [--echo] [--newest] [--oldest] [--older second ## Options -* `-c`, `--count`: Display the number of matching processes -* `-i`, `--ignore-case`: Make matches case-insensitive -* `-e`, `--echo`: Display what is killed -* `-n`, `--newest`: Kill the most recently created process only -* `-o`, `--oldest`: Select the least recently created process only -* `-O`, `--older`: Select only processes older than the specified number of seconds -* `-s signame`, `--signal signame`: Signal to send. The signal name or number may be used -* `-U uid-list`, `--uid uid-list`: Select only processes whose UID is in the given comma-separated list. Login name or numerical user ID may be used -* `-x`, `--exact`: Select only processes whose names match the given pattern exactly +- `-c`, `--count`: Display the number of matching processes +- `-i`, `--ignore-case`: Make matches case-insensitive +- `-e`, `--echo`: Display what is killed +- `-n`, `--newest`: Kill the most recently created process only +- `-o`, `--oldest`: Select the least recently created process only +- `-O`, `--older`: Select only processes older than the specified number of seconds +- `-s signame`, `--signal signame`: Signal to send. The signal name or number may be used +- `-U uid-list`, `--uid uid-list`: Select only processes whose UID is in the given comma-separated list. Login name or numerical user ID may be used +- `-x`, `--exact`: Select only processes whose names match the given pattern exactly ## Arguments -* `process-name`: Process name to search for +- `process-name`: Process name to search for ## See Also -* [`ps`(1)](help://man/1/ps) + +- [`ps`(1)](help://man/1/ps) diff --git a/Base/usr/share/man/man1/pmap.md b/Base/usr/share/man/man1/pmap.md index 2c6751db022..2ef46b68692 100644 --- a/Base/usr/share/man/man1/pmap.md +++ b/Base/usr/share/man/man1/pmap.md @@ -14,7 +14,7 @@ Print the memory map of a specified process. ## Options -* `-x`: Extended output +- `-x`: Extended output ## Examples @@ -23,5 +23,6 @@ $ pmap $$ ``` ## See also -* [`lsof`(1)](help://man/1/lsof) -* [`ps`(1)](help://man/1/ps) + +- [`lsof`(1)](help://man/1/lsof) +- [`ps`(1)](help://man/1/ps) diff --git a/Base/usr/share/man/man1/pmemdump.md b/Base/usr/share/man/man1/pmemdump.md index 670b991a4d6..aafdb6fb45e 100644 --- a/Base/usr/share/man/man1/pmemdump.md +++ b/Base/usr/share/man/man1/pmemdump.md @@ -12,16 +12,15 @@ $ pmemdump [-r] <offset> <length> Dump a portion of the physical memory space. - ## Options -* `-r`: Dump from /dev/mem with `read(2)` instead of doing `mmap(2)` on it. +- `-r`: Dump from /dev/mem with `read(2)` instead of doing `mmap(2)` on it. ## Examples ```sh -$ pmemdump -r 983040 65536 -$ pmemdump 983040 65536 +$ pmemdump -r 983040 65536 +$ pmemdump 983040 65536 ``` ## Notes @@ -35,4 +34,4 @@ offset fails. ## See also -* [`mem`(4)](help://man/4/mem) +- [`mem`(4)](help://man/4/mem) diff --git a/Base/usr/share/man/man1/printf.md b/Base/usr/share/man/man1/printf.md index 995c99c2539..07b5b50a6f1 100644 --- a/Base/usr/share/man/man1/printf.md +++ b/Base/usr/share/man/man1/printf.md @@ -13,25 +13,25 @@ $ printf <format> [arguments...] `printf` formats _argument_(s) according to _format_ and prints the result to standard output. _format_ is similar to the C printf format string, with the following differences: -- The format specifier `b` (`%b`) is not supported. -- The format specifiers that require a writable pointer (e.g. `n`) are not supported. -- The format specifier `q` (`%q`) has a different behavior, where it shall print a given string as a quoted string, which is safe to use in shell inputs. -- Common escape sequences are interpreted, namely the following: -| escape | description | -| :-: | :--- | -| `\\\\`| literal backslash | -| `\\"` | literal double quote | -| `\\a` | alert (BEL) | -| `\\b` | backspace | -| `\\c` | Ends the format string | -| `\\e` | escape (`\\x1b`) | -| `\\f` | form feed | -| `\\n` | newline | -| `\\r` | carriage return | -| `\\t` | tab | -| `\\v` | vertical tab | +- The format specifier `b` (`%b`) is not supported. +- The format specifiers that require a writable pointer (e.g. `n`) are not supported. +- The format specifier `q` (`%q`) has a different behavior, where it shall print a given string as a quoted string, which is safe to use in shell inputs. +- Common escape sequences are interpreted, namely the following: +| escape | description | +| :----: | :--------------------- | +| `\\\\` | literal backslash | +| `\\"` | literal double quote | +| `\\a` | alert (BEL) | +| `\\b` | backspace | +| `\\c` | Ends the format string | +| `\\e` | escape (`\\x1b`) | +| `\\f` | form feed | +| `\\n` | newline | +| `\\r` | carriage return | +| `\\t` | tab | +| `\\v` | vertical tab | The _format_ string is reapplied until all arguments are consumed, and a missing argument is treated as zero for numeric format specifiers, and an empty string for string format specifiers. @@ -50,4 +50,4 @@ $ printf '%d%d%d' 1 2 3 4 x ## See also -* [`echo`(1)](help://man/1/echo) +- [`echo`(1)](help://man/1/echo) diff --git a/Base/usr/share/man/man1/profile.md b/Base/usr/share/man/man1/profile.md index 166b57d18ce..6fefe1418d2 100644 --- a/Base/usr/share/man/man1/profile.md +++ b/Base/usr/share/man/man1/profile.md @@ -14,13 +14,13 @@ $ profile [-p PID] [-a] [-e] [-d] [-f] [-w] [-t event_type] [COMMAND_TO_PROFILE] ## Options -* `-p PID`: Target PID -* `-a`: Profile all processes (super-user only), result at /sys/kernel/profile -* `-e`: Enable -* `-d`: Disable -* `-f`: Free the profiling buffer for the associated process(es). -* `-w`: Enable profiling and wait for user input to disable. -* `-t event_type`: Enable tracking specific event type +- `-p PID`: Target PID +- `-a`: Profile all processes (super-user only), result at /sys/kernel/profile +- `-e`: Enable +- `-d`: Disable +- `-f`: Free the profiling buffer for the associated process(es). +- `-w`: Enable profiling and wait for user input to disable. +- `-t event_type`: Enable tracking specific event type Event type can be one of: sample, context_switch, page_fault, syscall, read, kmalloc and kfree. @@ -41,5 +41,5 @@ $ profile -t syscall -- echo "Hello friends!" ## See also -* [`Profiler`(1)](help://man/1/Applications/Profiler) GUI for viewing profiling data produced by `profile`. -* [`strace`(1)](help://man/1/strace) +- [`Profiler`(1)](help://man/1/Applications/Profiler) GUI for viewing profiling data produced by `profile`. +- [`strace`(1)](help://man/1/strace) diff --git a/Base/usr/share/man/man1/ps.md b/Base/usr/share/man/man1/ps.md index 742b37e8b3f..762a40aaf92 100644 --- a/Base/usr/share/man/man1/ps.md +++ b/Base/usr/share/man/man1/ps.md @@ -15,10 +15,10 @@ For each process, print its PID (process ID), to which TTY it belongs, and invok ## Options -* `-a`: Consider all processes that are associated with a TTY. -* `-A` or `-e`: Consider all processes, not just those in the current TTY. -* `-f`: Also print for each process: UID (as resolved username), PPID (parent PID), and STATE (Runnable, Sleeping, Selecting, Reading, etc.) -* `-o column-format`: Specify a user-defined format, as a list of column format specifiers separated by commas or spaces. +- `-a`: Consider all processes that are associated with a TTY. +- `-A` or `-e`: Consider all processes, not just those in the current TTY. +- `-f`: Also print for each process: UID (as resolved username), PPID (parent PID), and STATE (Runnable, Sleeping, Selecting, Reading, etc.) +- `-o column-format`: Specify a user-defined format, as a list of column format specifiers separated by commas or spaces. A column format specifier is of the form: `COLUMN_NAME[=COLUMN_TITLE]`. Where `COLUMN_NAME` is any of the following: `uid`, `pid`, `ppid`, `pgid`, `sid`, `state`, `tty`, or `cmd`. @@ -26,11 +26,11 @@ For each process, print its PID (process ID), to which TTY it belongs, and invok Specifying a `COLUMN_TITLE` will change the name shown in the column header. `COLUMN_TITLE` may be blank. If all given column titles are blank, the column header is omitted. -* `-p pid-list`: Select processes matching any of the given PIDs. `pid-list` is a list of PIDs, separated by commas or spaces. -* `--ppid pid-list`: Select processes whose PPID matches any of the given PIDs. `pid-list` is a list of PIDs, separated by commas or spaces. -* `-q pid-list`: Only consider the given PIDs, if they exist. Output the processes in the order provided by `pid-list`. `pid-list` is a list of PIDs, separated by commas or spaces. -* `-t tty-list`: Select processes associated with any of the given terminals. `tty-list` is a list of short TTY names (e.g: `pts:0`) or the full TTY device paths, separated by commas or spaces. -* `-u user-list`: Select processes matching any of the given UIDs. `user-list` is a list of UIDs or login names, separated by commas or spaces. +- `-p pid-list`: Select processes matching any of the given PIDs. `pid-list` is a list of PIDs, separated by commas or spaces. +- `--ppid pid-list`: Select processes whose PPID matches any of the given PIDs. `pid-list` is a list of PIDs, separated by commas or spaces. +- `-q pid-list`: Only consider the given PIDs, if they exist. Output the processes in the order provided by `pid-list`. `pid-list` is a list of PIDs, separated by commas or spaces. +- `-t tty-list`: Select processes associated with any of the given terminals. `tty-list` is a list of short TTY names (e.g: `pts:0`) or the full TTY device paths, separated by commas or spaces. +- `-u user-list`: Select processes matching any of the given UIDs. `user-list` is a list of UIDs or login names, separated by commas or spaces. ## Examples @@ -59,5 +59,6 @@ $ ps -q 42 -o cmd= ``` ## See Also -* [`pmap`(1)](help://man/1/pmap) -* [`lsof`(1)](help://man/1/lsof) + +- [`pmap`(1)](help://man/1/pmap) +- [`lsof`(1)](help://man/1/lsof) diff --git a/Base/usr/share/man/man1/pwd.md b/Base/usr/share/man/man1/pwd.md index be99452442d..7376f51b167 100644 --- a/Base/usr/share/man/man1/pwd.md +++ b/Base/usr/share/man/man1/pwd.md @@ -10,4 +10,4 @@ $ pwd ## Description -`pwd` prints the absolute pathname of the current working directory. \ No newline at end of file +`pwd` prints the absolute pathname of the current working directory. diff --git a/Base/usr/share/man/man1/readelf.md b/Base/usr/share/man/man1/readelf.md index ac814385006..1f99ebcf509 100644 --- a/Base/usr/share/man/man1/readelf.md +++ b/Base/usr/share/man/man1/readelf.md @@ -10,22 +10,22 @@ $ readelf [--all] [--file-header] [--program-headers] [--section-headers] [--hea ## Options -* `-a`, `--all`: Display all -* `-h`, `--file-header`: Display ELF header -* `-l`, `--program-headers`: Display program headers -* `-S`, `--section-headers`: Display section headers -* `-e`, `--headers`: Equivalent to: -h -l -S -s -r -d -n -u -c -* `-s`, `--syms`: Display the symbol table -* `--dyn-syms`: Display the dynamic symbol table -* `-d`, `--dynamic`: Display the dynamic section -* `-n`, `--notes`: Display core notes -* `-r`, `--relocs`: Display relocations -* `-u`, `--unwind`: Display unwind info -* `-c`, `--checksec`: Display security hardening info -* `-p section-name`, `--string-dump section-name`: Display the contents of a section as strings +- `-a`, `--all`: Display all +- `-h`, `--file-header`: Display ELF header +- `-l`, `--program-headers`: Display program headers +- `-S`, `--section-headers`: Display section headers +- `-e`, `--headers`: Equivalent to: -h -l -S -s -r -d -n -u -c +- `-s`, `--syms`: Display the symbol table +- `--dyn-syms`: Display the dynamic symbol table +- `-d`, `--dynamic`: Display the dynamic section +- `-n`, `--notes`: Display core notes +- `-r`, `--relocs`: Display relocations +- `-u`, `--unwind`: Display unwind info +- `-c`, `--checksec`: Display security hardening info +- `-p section-name`, `--string-dump section-name`: Display the contents of a section as strings ## Arguments -* `path`: ELF path +- `path`: ELF path <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man1/readlink.md b/Base/usr/share/man/man1/readlink.md index 0f70c1a1a4d..a84df79167f 100644 --- a/Base/usr/share/man/man1/readlink.md +++ b/Base/usr/share/man/man1/readlink.md @@ -14,7 +14,7 @@ Print targets of the specified symbolic links. ## Options -* `-n`, `--no-newline`: Do not output a newline after each target +- `-n`, `--no-newline`: Do not output a newline after each target ## Examples @@ -24,4 +24,4 @@ $ readlink /proc/self/cwd ## See also -* [`readlink`(2)](help://man/2/readlink) +- [`readlink`(2)](help://man/2/readlink) diff --git a/Base/usr/share/man/man1/realpath.md b/Base/usr/share/man/man1/realpath.md index 0e09eba2561..9f100264225 100644 --- a/Base/usr/share/man/man1/realpath.md +++ b/Base/usr/share/man/man1/realpath.md @@ -10,7 +10,7 @@ $ realpath [options] <paths> ## Options -* `-q`, `--quiet`: Suppress error messages. +- `-q`, `--quiet`: Suppress error messages. ## Description @@ -18,4 +18,4 @@ Show the 'real' path of a file, by resolving all symbolic links along the way. ## Arguments -* `paths`: Paths to resolve +- `paths`: Paths to resolve diff --git a/Base/usr/share/man/man1/rev.md b/Base/usr/share/man/man1/rev.md index a89cc040d53..43adabc3928 100644 --- a/Base/usr/share/man/man1/rev.md +++ b/Base/usr/share/man/man1/rev.md @@ -17,11 +17,12 @@ then `rev` will read from standard input. If the file `-` is specified then ## Arguments -* `file`: Files to print +- `file`: Files to print ## Examples To print two files 'foo' and 'bar' in reverse: + ```sh $ cat foo bar foo 1 @@ -36,6 +37,7 @@ $ rev foo bar ``` To list files with their names in reverse: + ```sh $ ls foo @@ -46,6 +48,7 @@ rab ``` To print a file 'foo' in reverse followed by the output of `ls` in reverse: + ```sh $ cat foo foo 1 diff --git a/Base/usr/share/man/man1/rm.md b/Base/usr/share/man/man1/rm.md index bf544b5a240..ea322205a57 100644 --- a/Base/usr/share/man/man1/rm.md +++ b/Base/usr/share/man/man1/rm.md @@ -16,10 +16,10 @@ If a directory is specified in `path`, the `-r` (recursive) flag is required. Ot ## Options -* `-r`, `--recursive`: Remove files and directories recursively -* `-f`, `--force`: Do not prompt before removing -* `-v`, `--verbose`: Display what files are removed -* `--no-preserve-root`: Do not treat '/' specially +- `-r`, `--recursive`: Remove files and directories recursively +- `-f`, `--force`: Do not prompt before removing +- `-v`, `--verbose`: Display what files are removed +- `--no-preserve-root`: Do not treat '/' specially ## Examples @@ -32,4 +32,5 @@ $ rm -r Tests ``` ## See also -* [`rmdir`(1)](help://man/1/rmdir) to just delete empty directories + +- [`rmdir`(1)](help://man/1/rmdir) to just delete empty directories diff --git a/Base/usr/share/man/man1/rmdir.md b/Base/usr/share/man/man1/rmdir.md index 8865770a0ec..f57c65bc75e 100644 --- a/Base/usr/share/man/man1/rmdir.md +++ b/Base/usr/share/man/man1/rmdir.md @@ -5,7 +5,7 @@ rmdir - remove empty directories ## Synopsis ```**sh -$ rmdir `[directory...]` +$ rmdir `[directory...]` ``` ## Description @@ -14,12 +14,12 @@ Remove given `directory(ies)`, if they are empty ## Options -* `-p`, `--parents`: Remove all directories in each given path -* `-v`, `--verbose`: List each directory as it is removed +- `-p`, `--parents`: Remove all directories in each given path +- `-v`, `--verbose`: List each directory as it is removed ## Arguments -* `directory`: directory(ies) to remove +- `directory`: directory(ies) to remove ## Examples @@ -42,5 +42,6 @@ $ rmdir -p foo/bar/baz/ ``` ## See also -* [`mkdir`(1)](help://man/1/mkdir) -* [`rm`(1)](help://man/1/rm) + +- [`mkdir`(1)](help://man/1/mkdir) +- [`rm`(1)](help://man/1/rm) diff --git a/Base/usr/share/man/man1/shot.md b/Base/usr/share/man/man1/shot.md index 6701c8cbdce..2e4027c9e1d 100644 --- a/Base/usr/share/man/man1/shot.md +++ b/Base/usr/share/man/man1/shot.md @@ -10,14 +10,14 @@ $ shot [--clipboard] [--delay seconds] [--screen index] [--region] [--edit] [out ## Options -* `-c`, `--clipboard`: Output to clipboard -* `-d seconds`, `--delay seconds`: Seconds to wait before taking a screenshot -* `-s index`, `--screen index`: The index of the screen (default: -1 for all screens) -* `-r`, `--region`: Select a region to capture -* `-e`, `--edit`: Open in PixelPaint +- `-c`, `--clipboard`: Output to clipboard +- `-d seconds`, `--delay seconds`: Seconds to wait before taking a screenshot +- `-s index`, `--screen index`: The index of the screen (default: -1 for all screens) +- `-r`, `--region`: Select a region to capture +- `-e`, `--edit`: Open in PixelPaint ## Arguments -* `output`: Output filename +- `output`: Output filename <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man1/shred.md b/Base/usr/share/man/man1/shred.md index 8c1def0ac42..75f35637a01 100644 --- a/Base/usr/share/man/man1/shred.md +++ b/Base/usr/share/man/man1/shred.md @@ -14,15 +14,15 @@ $ shred [options...] [path...] ## Options -* `--help`: Display this message -* `-v`, `--verbose`: Show progress during the shred operation -* `-n`, `--iterations`: Iterations count of shred operation -* `-u`: Deallocate and remove file after overwriting -* `--random-source`: Get random bytes from a file other than /dev/random +- `--help`: Display this message +- `-v`, `--verbose`: Show progress during the shred operation +- `-n`, `--iterations`: Iterations count of shred operation +- `-u`: Deallocate and remove file after overwriting +- `--random-source`: Get random bytes from a file other than /dev/random ## Arguments -* `path`: Files to shred +- `path`: Files to shred ## Examples @@ -36,4 +36,5 @@ $ shred -v --iterations 10 /tmp/FILE_TO_BE_SHREDDED ``` ## See also -* [`rm`(1)](help://man/1/rm) to delete a file or directory without overwriting the content first + +- [`rm`(1)](help://man/1/rm) to delete a file or directory without overwriting the content first diff --git a/Base/usr/share/man/man1/shuf.md b/Base/usr/share/man/man1/shuf.md index f1aadaaab6f..c555a36adc3 100644 --- a/Base/usr/share/man/man1/shuf.md +++ b/Base/usr/share/man/man1/shuf.md @@ -10,10 +10,10 @@ $ shuf [--head-count count] [--repeat] [--zero-terminated] [file] ## Options -* `-n count`, `--head-count count`: Output at most "count" lines -* `-r`, `--repeat`: Pick lines at random rather than shuffling. The program will continue indefinitely if no `-n` option is specified -* `-z`, `--zero-terminated`: Split input on \0, not newline +- `-n count`, `--head-count count`: Output at most "count" lines +- `-r`, `--repeat`: Pick lines at random rather than shuffling. The program will continue indefinitely if no `-n` option is specified +- `-z`, `--zero-terminated`: Split input on \0, not newline ## Arguments -* `file`: File +- `file`: File diff --git a/Base/usr/share/man/man1/sizefmt.md b/Base/usr/share/man/man1/sizefmt.md index d729cd1bd35..0269a536720 100644 --- a/Base/usr/share/man/man1/sizefmt.md +++ b/Base/usr/share/man/man1/sizefmt.md @@ -16,7 +16,7 @@ suffixes (KB for Kilobytes, or KiB for Kibibytes, for example). ## Arguments -* `integer-with-suffix`: a number with a suffix (possibly). +- `integer-with-suffix`: a number with a suffix (possibly). ## Examples diff --git a/Base/usr/share/man/man1/sleep.md b/Base/usr/share/man/man1/sleep.md index 2c993d91c4f..9595d10d520 100644 --- a/Base/usr/share/man/man1/sleep.md +++ b/Base/usr/share/man/man1/sleep.md @@ -10,7 +10,7 @@ $ sleep <seconds> ## Arguments -* `seconds`: Number of seconds to sleep +- `seconds`: Number of seconds to sleep ## Description diff --git a/Base/usr/share/man/man1/slugify.md b/Base/usr/share/man/man1/slugify.md index 651ad921daa..2794914c1e3 100644 --- a/Base/usr/share/man/man1/slugify.md +++ b/Base/usr/share/man/man1/slugify.md @@ -14,9 +14,9 @@ Slugify is a simple text to slug transform utility and prints the result. ## Options -* `-f`, `--format`: Output format to choose from 'md', 'html', 'plain'. (default: md) -* `-g`, `--glue`: Specify delimiter (_single character only_) to join the parts. (default: -) -* `-s`, `--single-page`: Prepends hash/pound (#) to the slugified string when set, otherwise slash (/). Useful for markdowns like in GitHub (default: false) +- `-f`, `--format`: Output format to choose from 'md', 'html', 'plain'. (default: md) +- `-g`, `--glue`: Specify delimiter (_single character only_) to join the parts. (default: -) +- `-s`, `--single-page`: Prepends hash/pound (#) to the slugified string when set, otherwise slash (/). Useful for markdowns like in GitHub (default: false) ## Examples diff --git a/Base/usr/share/man/man1/sort.md b/Base/usr/share/man/man1/sort.md index cf298bb423c..320df18a6dc 100644 --- a/Base/usr/share/man/man1/sort.md +++ b/Base/usr/share/man/man1/sort.md @@ -14,12 +14,12 @@ Sort each lines of INPUT (or standard input). A quick sort algorithm is used. ## Options -* `-k keydef`, `--key-field keydef`: The field to sort by -* `-u`, `--unique`: Don't emit duplicate lines -* `-n`, `--numeric`: Treat the key field as a number -* `-t char`, `--sep char`: The separator to split fields by -* `-r`, `--reverse`: Sort in reverse order -* `-z`, `--zero-terminated`: Use `\0` as the line delimiter instead of a newline +- `-k keydef`, `--key-field keydef`: The field to sort by +- `-u`, `--unique`: Don't emit duplicate lines +- `-n`, `--numeric`: Treat the key field as a number +- `-t char`, `--sep char`: The separator to split fields by +- `-r`, `--reverse`: Sort in reverse order +- `-z`, `--zero-terminated`: Use `\0` as the line delimiter instead of a newline ## Examples @@ -29,4 +29,3 @@ Friends! Hello Well ``` - diff --git a/Base/usr/share/man/man1/sql.md b/Base/usr/share/man/man1/sql.md index c3d046c602b..990dc4d0992 100644 --- a/Base/usr/share/man/man1/sql.md +++ b/Base/usr/share/man/man1/sql.md @@ -14,9 +14,9 @@ This is a client for the SerenitySQL database server. ## Options -* `-d database`, `--database database`: Database to connect to -* `-r file`, `--read file`: File to read -* `-s file`, `--source file`: File to source -* `-n`, `--no-sqlrc`: Don't read ~/.sqlrc +- `-d database`, `--database database`: Database to connect to +- `-r file`, `--read file`: File to read +- `-s file`, `--source file`: File to source +- `-n`, `--no-sqlrc`: Don't read ~/.sqlrc <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man1/stat.md b/Base/usr/share/man/man1/stat.md index 8b12a7bfc5b..781fe06a568 100644 --- a/Base/usr/share/man/man1/stat.md +++ b/Base/usr/share/man/man1/stat.md @@ -14,9 +14,9 @@ Display file status and provide more information about that file. ## Options -* `-L`: Follow links to files -* `--help`: Display help message and exit -* `--version`: Print version +- `-L`: Follow links to files +- `--help`: Display help message and exit +- `--version`: Print version ## Examples diff --git a/Base/usr/share/man/man1/strace.md b/Base/usr/share/man/man1/strace.md index 7dbe9d2161e..beaff1111c9 100644 --- a/Base/usr/share/man/man1/strace.md +++ b/Base/usr/share/man/man1/strace.md @@ -14,15 +14,16 @@ Trace all syscalls and their result. ## Options -* `-p pid`, `--pid pid`: Trace the given PID -* `-o output`, `--output output`: Filename to write output to -* `-e exclude`, `--exclude exclude`: Comma-delimited syscalls to exclude -* `-i include`, `--include include`: Comma-delimited syscalls to include +- `-p pid`, `--pid pid`: Trace the given PID +- `-o output`, `--output output`: Filename to write output to +- `-e exclude`, `--exclude exclude`: Comma-delimited syscalls to exclude +- `-i include`, `--include include`: Comma-delimited syscalls to include ## Arguments -* `argument`: Arguments to exec +- `argument`: Arguments to exec ## See Also -* [`profile`(1)](help://man/1/profile) -* [`Profiler`(1)](help://man/1/Applications/Profiler) + +- [`profile`(1)](help://man/1/profile) +- [`Profiler`(1)](help://man/1/Applications/Profiler) diff --git a/Base/usr/share/man/man1/strings.md b/Base/usr/share/man/man1/strings.md index 22cce4b9e59..2f3dfba671e 100644 --- a/Base/usr/share/man/man1/strings.md +++ b/Base/usr/share/man/man1/strings.md @@ -5,7 +5,7 @@ strings - find printable strings in files ## Synopsis ```**sh -$ strings [--bytes NUMBER] [--print-file-name] [-o] [--radix FORMAT] [PATHS...] +$ strings [--bytes NUMBER] [--print-file-name] [-o] [--radix FORMAT] [PATHS...] ``` ## Description @@ -14,10 +14,10 @@ $ strings [--bytes NUMBER] [--print-file-name] [-o] [--radix FORMAT] [PATHS...] ## Options -* `-n NUMBER`, `--bytes NUMBER`: Specify the minimum string length (4 is default). -* `-f`, `--print-file-name`: Print the name of the file before each string. -* `-o`: Equivalent to specifying `-t o`. -* `-t FORMAT`, `--radix FORMAT`: Write each string preceded by its byte offset from the start of the file in the specified `FORMAT`, where `FORMAT` matches one of the following: `d` (decimal), `o` (octal), or `x` (hexidecimal). +- `-n NUMBER`, `--bytes NUMBER`: Specify the minimum string length (4 is default). +- `-f`, `--print-file-name`: Print the name of the file before each string. +- `-o`: Equivalent to specifying `-t o`. +- `-t FORMAT`, `--radix FORMAT`: Write each string preceded by its byte offset from the start of the file in the specified `FORMAT`, where `FORMAT` matches one of the following: `d` (decimal), `o` (octal), or `x` (hexidecimal). ## Examples diff --git a/Base/usr/share/man/man1/su.md b/Base/usr/share/man/man1/su.md index f9eab53327f..f9232da36a6 100644 --- a/Base/usr/share/man/man1/su.md +++ b/Base/usr/share/man/man1/su.md @@ -13,16 +13,16 @@ $ su [-] [user] [-c command] `su`: Switch to another user. -When called with no user-specified, `su` defaults to switch to the *root* user. Need to enter the password if the user switch to has one. +When called with no user-specified, `su` defaults to switch to the _root_ user. Need to enter the password if the user switch to has one. ## Options -* `-`, `-l`, `--login`: Start the shell as it was a real login -* `-c`, `--command`: Execute a command using `/bin/sh` instead of starting an interactive shell +- `-`, `-l`, `--login`: Start the shell as it was a real login +- `-c`, `--command`: Execute a command using `/bin/sh` instead of starting an interactive shell ## Arguments -* `user`: User to switch to (defaults to the user with UID 0) +- `user`: User to switch to (defaults to the user with UID 0) ## Examples @@ -39,4 +39,5 @@ $ su nona ``` ## See also -* [`pls`(8)](help://man/8/pls) + +- [`pls`(8)](help://man/8/pls) diff --git a/Base/usr/share/man/man1/syscall.md b/Base/usr/share/man/man1/syscall.md index d3bc9e56700..2c669eaf8ce 100644 --- a/Base/usr/share/man/man1/syscall.md +++ b/Base/usr/share/man/man1/syscall.md @@ -14,9 +14,9 @@ The `syscall` utility can be used to invoke a system call with the given argumen ## Options -* `-o`: Output the contents of the buffer argument specified as buf to stdout. -* `-l`: Print a space separated list of all the Serenity system calls and exit. Note that not all the system calls can be invoked using this tool. -* `-h`: Print a help message and exit. +- `-o`: Output the contents of the buffer argument specified as buf to stdout. +- `-l`: Print a space separated list of all the Serenity system calls and exit. Note that not all the system calls can be invoked using this tool. +- `-h`: Print a help message and exit. ## Examples @@ -59,4 +59,3 @@ $ syscall exit 2 ## History This is a direct port of a utility with the same name originated from the Plan 9 operating system. - diff --git a/Base/usr/share/man/man1/tail.md b/Base/usr/share/man/man1/tail.md index c16fa842fb9..30360ef003c 100644 --- a/Base/usr/share/man/man1/tail.md +++ b/Base/usr/share/man/man1/tail.md @@ -14,42 +14,47 @@ $ tail [-f] [-n number] [file] ## Options -* `-f`, `--follow`: Output data as it is written to the file -* `-n [+]NUM`, `--lines [+]NUM`: output the last NUM lines, instead of the last 10; or use -n +NUM to output starting with line NUM -* `-c [+]NUM`, `--bytes [+]NUM`: output the last NUM bytes; or use -n +NUM to output starting with byte NUM +- `-f`, `--follow`: Output data as it is written to the file +- `-n [+]NUM`, `--lines [+]NUM`: output the last NUM lines, instead of the last 10; or use -n +NUM to output starting with line NUM +- `-c [+]NUM`, `--bytes [+]NUM`: output the last NUM bytes; or use -n +NUM to output starting with byte NUM ## Arguments -* `file`: Target file. If unspecified or `-`, defaults to the standard input. +- `file`: Target file. If unspecified or `-`, defaults to the standard input. ## Examples Print the last 10 lines of README.md: + ```sh $ tail README.md ``` Print the last 42 lines of todo.txt: + ```sh $ tail -n 42 todo.txt ``` Print the last lines as they are written to logs.log: + ```sh $ tail -f logs.log ``` Print everything but the first line of foobar.csv + ```sh $ tail -n +2 foobar.csv ``` Print the last 1337 bytes of leet.txt + ```sh $ tail -c 1337 leet.txt ``` ## See also -* [`head`(1)](help://man/1/head) -* [`cat`(1)](help://man/1/cat) +- [`head`(1)](help://man/1/head) +- [`cat`(1)](help://man/1/cat) diff --git a/Base/usr/share/man/man1/tar.md b/Base/usr/share/man/man1/tar.md index f1c1008ffe2..9656c240458 100644 --- a/Base/usr/share/man/man1/tar.md +++ b/Base/usr/share/man/man1/tar.md @@ -17,16 +17,16 @@ Files may also be compressed and decompressed using GNU Zip (GZIP) compression. ## Options -* `-c`, `--create`: Create archive -* `-x`, `--extract`: Extract archive -* `-t`, `--list`: List contents -* `-v`, `--verbose`: Print paths -* `-z`, `--gzip`: Compress or decompress file using gzip -* `--lzma`: Compress or decompress file using lzma -* `-J`, `--xz`: Compress or decompress file using xz -* `--no-auto-compress`: Do not use the archive suffix to select the compression algorithm -* `-C DIRECTORY`, `--directory DIRECTORY`: Directory to extract to/create from -* `-f FILE`, `--file FILE`: Archive file +- `-c`, `--create`: Create archive +- `-x`, `--extract`: Extract archive +- `-t`, `--list`: List contents +- `-v`, `--verbose`: Print paths +- `-z`, `--gzip`: Compress or decompress file using gzip +- `--lzma`: Compress or decompress file using lzma +- `-J`, `--xz`: Compress or decompress file using xz +- `--no-auto-compress`: Do not use the archive suffix to select the compression algorithm +- `-C DIRECTORY`, `--directory DIRECTORY`: Directory to extract to/create from +- `-f FILE`, `--file FILE`: Archive file ## Examples @@ -43,4 +43,4 @@ $ tar -x -f archive.tar ## See also -* [`unzip`(1)](help://man/1/unzip) +- [`unzip`(1)](help://man/1/unzip) diff --git a/Base/usr/share/man/man1/test-js.md b/Base/usr/share/man/man1/test-js.md index 4639eb9d36c..90c81eb10f1 100644 --- a/Base/usr/share/man/man1/test-js.md +++ b/Base/usr/share/man/man1/test-js.md @@ -23,15 +23,15 @@ You can disable output from `dbgln()` calls by setting the `DISABLE_DBG_OUTPUT` ## Options -* `-t`, `--show-time`: Show duration of each test -* `-p`, `--show-progress`: Show progress with OSC 9 (true, false) -* `-j`, `--json`: Show results as JSON -* `--per-file`: Show detailed per-file results as JSON (implies -j) -* `-g`, `--collect-often`: Collect garbage after every allocation -* `-b`, `--run-bytecode`: Use the bytecode interpreter -* `-d`, `--dump-bytecode`: Dump the bytecode -* `-f glob`, `--filter glob`: Only run tests matching the given glob -* `--test262-parser-tests`: Run test262 parser tests +- `-t`, `--show-time`: Show duration of each test +- `-p`, `--show-progress`: Show progress with OSC 9 (true, false) +- `-j`, `--json`: Show results as JSON +- `--per-file`: Show detailed per-file results as JSON (implies -j) +- `-g`, `--collect-often`: Collect garbage after every allocation +- `-b`, `--run-bytecode`: Use the bytecode interpreter +- `-d`, `--dump-bytecode`: Dump the bytecode +- `-f glob`, `--filter glob`: Only run tests matching the given glob +- `--test262-parser-tests`: Run test262 parser tests ## Examples @@ -49,4 +49,4 @@ describe("Examples from Gary Bernhardt's 'Wat' talk", () => { ## See also -* [`js`(1)](help://man/1/js) +- [`js`(1)](help://man/1/js) diff --git a/Base/usr/share/man/man1/test.md b/Base/usr/share/man/man1/test.md index 50402a96cb7..e3f8ce99a4e 100644 --- a/Base/usr/share/man/man1/test.md +++ b/Base/usr/share/man/man1/test.md @@ -24,65 +24,63 @@ The expression can take any of the following forms: ### Grouping -* `( <expression> )` value of expression +- `( <expression> )` value of expression ### Boolean operations -* `! <expression>` negation of expression -* `<expression> -a <expression>` boolean conjunction of the values -* `<expression> -o <expression>` boolean disjunction of the values +- `! <expression>` negation of expression +- `<expression> -a <expression>` boolean conjunction of the values +- `<expression> -o <expression>` boolean disjunction of the values ### String comparison -* `<string>` whether the string is non-empty -* `-n <string>` whether the string is non-empty -* `-z <string>` whether the string is empty -* `<string> = <string>` whether the two strings are equal -* `<string> != <string>` whether the two strings not equal +- `<string>` whether the string is non-empty +- `-n <string>` whether the string is non-empty +- `-z <string>` whether the string is empty +- `<string> = <string>` whether the two strings are equal +- `<string> != <string>` whether the two strings not equal ### Integer comparison -* `<integer> -eq <integer>` whether the two integers are equal -* `<integer> -ne <integer>` whether the two integers are not equal -* `<integer> -lt <integer>` whether the integer on the left is less than the integer on the right -* `<integer> -gt <integer>` whether the integer on the left is greater than the integer on the right -* `<integer> -le <integer>` whether the integer on the left is less than or equal to the integer on the right -* `<integer> -ge <integer>` whether the integer on the left is greater than or equal to the integer on the right +- `<integer> -eq <integer>` whether the two integers are equal +- `<integer> -ne <integer>` whether the two integers are not equal +- `<integer> -lt <integer>` whether the integer on the left is less than the integer on the right +- `<integer> -gt <integer>` whether the integer on the left is greater than the integer on the right +- `<integer> -le <integer>` whether the integer on the left is less than or equal to the integer on the right +- `<integer> -ge <integer>` whether the integer on the left is greater than or equal to the integer on the right ### File comparison -* `<file> -ef <file>` whether the two files are the same (have the same inode and device numbers) -* `<file> -nt <file>` whether the file on the left is newer than the file on the right (modification date is used) -* `<file> -ot <file>` whether the file on the left is older than the file on the right (modification date is used) +- `<file> -ef <file>` whether the two files are the same (have the same inode and device numbers) +- `<file> -nt <file>` whether the file on the left is newer than the file on the right (modification date is used) +- `<file> -ot <file>` whether the file on the left is older than the file on the right (modification date is used) ### File type checks -* `-b <file>` whether the file is a block device -* `-c <file>` whether the file is a character device -* `-f <file>` whether the file is a regular file -* `-d <file>` whether the file is a directory -* `-p <file>` whether the file is a pipe -* `-S <file>` whether the file is a socket -* `-h <file>`, `-L <file>` whether the file is a symbolic link +- `-b <file>` whether the file is a block device +- `-c <file>` whether the file is a character device +- `-f <file>` whether the file is a regular file +- `-d <file>` whether the file is a directory +- `-p <file>` whether the file is a pipe +- `-S <file>` whether the file is a socket +- `-h <file>`, `-L <file>` whether the file is a symbolic link ### File permission checks -* `-r <file>` whether the current user has read access to the file -* `-w <file>` whether the current user has write access to the file -* `-x <file>` whether the current user has execute access to the file -* `-e <file>` whether the file exists -* `-g <file>` whether the file exists and has the set-group-ID bit set -* `-G <file>` whether the file exists and is owned by the effective group ID -* `-k <file>` whether the file exists and has the sticky bit set -* `-O <file>` whether the file exists and is owned by the effective user ID -* `-u <file>` whether the file exists and has the set-user-ID bit set - +- `-r <file>` whether the current user has read access to the file +- `-w <file>` whether the current user has write access to the file +- `-x <file>` whether the current user has execute access to the file +- `-e <file>` whether the file exists +- `-g <file>` whether the file exists and has the set-group-ID bit set +- `-G <file>` whether the file exists and is owned by the effective group ID +- `-k <file>` whether the file exists and has the sticky bit set +- `-O <file>` whether the file exists and is owned by the effective user ID +- `-u <file>` whether the file exists and has the set-user-ID bit set Except for `-h/-L`, all file checks dereference symbolic links. NOTE: Your shell might have a builtin named 'test' and/or '[', please refer to your shell's documentation for further details. - ## Options None. @@ -97,5 +95,6 @@ $ /bin/test \( 10 -gt 20 \) -o \( ! 10 -ne 10 \) && echo "magic numbers!" ``` ## See Also -* [`expr`(1)](help://man/1/expr) -* [`find`(1)](help://man/1/find) + +- [`expr`(1)](help://man/1/expr) +- [`find`(1)](help://man/1/find) diff --git a/Base/usr/share/man/man1/timezone.md b/Base/usr/share/man/man1/timezone.md index 9ad45046b39..4a24411e647 100644 --- a/Base/usr/share/man/man1/timezone.md +++ b/Base/usr/share/man/man1/timezone.md @@ -14,26 +14,29 @@ The `timezone` utility can be used to view or change the current system time zon ## Options -* `-l`, `--list-time-zones`: View all available time zones and exit. +- `-l`, `--list-time-zones`: View all available time zones and exit. ## Arguments -* `time-zone`: Time zone to change the system to use. +- `time-zone`: Time zone to change the system to use. ## Examples Get the current system time zone: + ```sh $ timezone UTC ``` Set the system time zone: + ```sh $ timezone America/New_York ``` View all available time zones: + ```sh $ timezone --list-time-zones Africa/Abidjan diff --git a/Base/usr/share/man/man1/top.md b/Base/usr/share/man/man1/top.md index f5076d0ad58..ccaefcf05d5 100644 --- a/Base/usr/share/man/man1/top.md +++ b/Base/usr/share/man/man1/top.md @@ -10,6 +10,6 @@ $ top [--delay-time secs] [--pids pid-list] [--sort-by field] ## Options -* `-d`, `--delay-time`: Delay time interval in seconds -* `-p`, `--pids`: A comma-separated list of pids to filter by. This option may be used multiple times. -* `-s`, `--sort-by`: Sort by field [pid, tid, pri, user, state, virt, phys, cpu, name] +- `-d`, `--delay-time`: Delay time interval in seconds +- `-p`, `--pids`: A comma-separated list of pids to filter by. This option may be used multiple times. +- `-s`, `--sort-by`: Sort by field [pid, tid, pri, user, state, virt, phys, cpu, name] diff --git a/Base/usr/share/man/man1/touch.md b/Base/usr/share/man/man1/touch.md index 864b1296a69..61a9de44b4b 100644 --- a/Base/usr/share/man/man1/touch.md +++ b/Base/usr/share/man/man1/touch.md @@ -18,14 +18,14 @@ that does not exist. ## Options -* `-a`: Change access time of file -* `-c`: Do not create a file if it does not exist -* `-m`: Change modification time of file -* `-r`: Use time of file specified by reference path instead of current time -* `-t`: Use specified time in format [[CC]YY]MMDDhhmm[.SS] instead of current -time -* `-d`: Use specified datetime in formats YYYY-MM-DDThh:mm:SS[.frac][tz] or -YYYY-MM-DDThh:mm:SS[,frac][tz] instead of current time +- `-a`: Change access time of file +- `-c`: Do not create a file if it does not exist +- `-m`: Change modification time of file +- `-r`: Use time of file specified by reference path instead of current time +- `-t`: Use specified time in format [[CC]YY]MMDDhhmm[.SS] instead of current + time +- `-d`: Use specified datetime in formats YYYY-MM-DDThh:mm:SS[.frac][tz] or + YYYY-MM-DDThh:mm:SS[,frac][tz] instead of current time ## Examples @@ -51,6 +51,7 @@ $ touch -r anotherfile thatfile ``` ## See also -* [`mktemp`(1)](help://man/1/mktemp) to create a temporary file -* [`futimens`(2)](help://man/3/futimens) -* [`utimensat`(2)](help://man/3/utimensat) + +- [`mktemp`(1)](help://man/1/mktemp) to create a temporary file +- [`futimens`(2)](help://man/3/futimens) +- [`utimensat`(2)](help://man/3/utimensat) diff --git a/Base/usr/share/man/man1/tr.md b/Base/usr/share/man/man1/tr.md index 6d030f06558..1d2040e8e53 100644 --- a/Base/usr/share/man/man1/tr.md +++ b/Base/usr/share/man/man1/tr.md @@ -10,13 +10,13 @@ $ tr [--complement] [--delete] [--squeeze-repeats] <from> [to] ## Options -* `-c`, `--complement`: Take the complement of the first set -* `-d`, `--delete`: Delete characters instead of replacing -* `-s`, `--squeeze-repeats`: Omit repeated characters listed in the last given set from the output +- `-c`, `--complement`: Take the complement of the first set +- `-d`, `--delete`: Delete characters instead of replacing +- `-s`, `--squeeze-repeats`: Omit repeated characters listed in the last given set from the output ## Arguments -* `from`: Set of characters to translate from -* `to`: Set of characters to translate to +- `from`: Set of characters to translate from +- `to`: Set of characters to translate to <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man1/traceroute.md b/Base/usr/share/man/man1/traceroute.md index bf79588eb12..36831de0970 100644 --- a/Base/usr/share/man/man1/traceroute.md +++ b/Base/usr/share/man/man1/traceroute.md @@ -10,12 +10,12 @@ $ traceroute [--max-hops hops] [--max-retries tries] [--timeout seconds] <destin ## Options -* `-h hops`, `--max-hops hops`: use at most <hops> to the destination -* `-r tries`, `--max-retries tries`: retry TTL at most <tries> times -* `-t seconds`, `--timeout seconds`: wait at most <seconds> for a response +- `-h hops`, `--max-hops hops`: use at most <hops> to the destination +- `-r tries`, `--max-retries tries`: retry TTL at most <tries> times +- `-t seconds`, `--timeout seconds`: wait at most <seconds> for a response ## Arguments -* `destination`: destination +- `destination`: destination <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man1/tree.md b/Base/usr/share/man/man1/tree.md index 14c3599f060..bc2022478cf 100644 --- a/Base/usr/share/man/man1/tree.md +++ b/Base/usr/share/man/man1/tree.md @@ -10,13 +10,14 @@ $ tree [--all] [--only-directories] [--maximum-depth level] [directories...] ## Options -* `-a`, `--all`: Show hidden files -* `-d`, `--only-directories`: Show only directories -* `-L level`, `--maximum-depth level`: Maximum depth of the tree +- `-a`, `--all`: Show hidden files +- `-d`, `--only-directories`: Show only directories +- `-L level`, `--maximum-depth level`: Maximum depth of the tree ## Arguments -* `directories`: Directories to print +- `directories`: Directories to print ## See also -* [`ls`(1)](help://man/1/ls) to show just the contents of one directory + +- [`ls`(1)](help://man/1/ls) to show just the contents of one directory diff --git a/Base/usr/share/man/man1/truncate.md b/Base/usr/share/man/man1/truncate.md index 158555d22a0..e7dcfe5cd87 100644 --- a/Base/usr/share/man/man1/truncate.md +++ b/Base/usr/share/man/man1/truncate.md @@ -10,11 +10,11 @@ $ truncate [--size size] [--reference file] <file> ## Options -* `-s size`, `--size size`: Resize the target file to (or by) this size. Prefix with + or - to expand or shrink the file, or a bare number to set the size exactly -* `-r file`, `--reference file`: Resize the target file to match the size of this one +- `-s size`, `--size size`: Resize the target file to (or by) this size. Prefix with + or - to expand or shrink the file, or a bare number to set the size exactly +- `-r file`, `--reference file`: Resize the target file to match the size of this one ## Arguments -* `file`: File path +- `file`: File path <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man1/uname.md b/Base/usr/share/man/man1/uname.md index c824d676158..4e3975c5514 100644 --- a/Base/usr/share/man/man1/uname.md +++ b/Base/usr/share/man/man1/uname.md @@ -15,12 +15,12 @@ system call. ## Options -* `-s`: Print the system name -* `-n`: Print the node name (hostname) -* `-r`: Print the system release version -* `-v`: Print the version of the release -* `-m`: Print the machine type -* `-a`: Print all of the above +- `-s`: Print the system name +- `-n`: Print the node name (hostname) +- `-r`: Print the system release version +- `-v`: Print the version of the release +- `-m`: Print the machine type +- `-a`: Print all of the above ## Examples @@ -31,4 +31,4 @@ Serenity x86_64 ## See also -* [`uname`(2)](help://man/2/uname) +- [`uname`(2)](help://man/2/uname) diff --git a/Base/usr/share/man/man1/uniq.md b/Base/usr/share/man/man1/uniq.md index 401f8dc39d4..33c472a5235 100644 --- a/Base/usr/share/man/man1/uniq.md +++ b/Base/usr/share/man/man1/uniq.md @@ -14,28 +14,31 @@ Filter out repeated adjacent lines from INPUT (or standard input) and write to O ## Options -* `-c`, `--count`: Precede each line with its number of occurrences. -* `-d`, `--repeated`: Only print repeated lines. -* `-u`, `--unique`: Only print unique lines (default). -* `-i`, `--ignore-case`: Ignore case when comparing lines. -* `-f N`, `--skip-fields N`: Skip first N fields of each line before comparing. -* `-s N`, `--skip-chars N`: Skip first N chars of each line before comparing. -* `--help`: Display help message and exit. -* `--version`: Print version. +- `-c`, `--count`: Precede each line with its number of occurrences. +- `-d`, `--repeated`: Only print repeated lines. +- `-u`, `--unique`: Only print unique lines (default). +- `-i`, `--ignore-case`: Ignore case when comparing lines. +- `-f N`, `--skip-fields N`: Skip first N fields of each line before comparing. +- `-s N`, `--skip-chars N`: Skip first N chars of each line before comparing. +- `--help`: Display help message and exit. +- `--version`: Print version. ## Examples Filter out repeated lines from README.md and write to standard output: + ```sh $ uniq README.md ``` Filter out repeated lines from README.md and write to UNIQUE.md: + ```sh $ uniq README.md UNIQUE.md ``` Filter out repeated lines from standard input with their occurrence count: + ```sh $ echo "Well\nWell\nWell\nHello Friends!" | uniq -c 3 Well @@ -43,8 +46,8 @@ $ echo "Well\nWell\nWell\nHello Friends!" | uniq -c ``` Filter out repeated lines, ignoring the first field ("XXXX" and "ZZZZ") and the four chars after it (" ABC" and " BCA", thus comparing only the "D"s — which are equal indeed): + ```sh $ echo "XXXX ABCD\nZZZZ BCAD" | uniq -f1 -s4 ZZZZ BCAD ``` - diff --git a/Base/usr/share/man/man1/unveil.md b/Base/usr/share/man/man1/unveil.md index 183dac118e2..3256ed20b6b 100644 --- a/Base/usr/share/man/man1/unveil.md +++ b/Base/usr/share/man/man1/unveil.md @@ -14,21 +14,24 @@ Run a command under certain path restrictions by using [`unveil`(2)](help://man/ ## Options -* `-u`, `--path`: Unveil a path, with the format of `permissions,path` +- `-u`, `--path`: Unveil a path, with the format of `permissions,path` ## Examples Run `ls -la /sys/kernel` with restricted access to certain paths: + ```sh $ unveil --path=r,/etc/timezone --path=r,/usr/lib --path=r,/sys/ --path=r,/etc/passwd --path=r,/etc/group ls -la /sys/kernel ``` Run `ps -ef` with restricted access to certain paths: + ```sh $ unveil --path=r,/etc/timezone --path=r,/usr/lib --path=r,/sys/ --path=r,/etc/passwd --path=r,/etc/group ps -ef ``` ## See also -* [`pledge`(2)](help://man/2/pledge) -* [`unveil`(2)](help://man/2/unveil) -* [`Mitigations`(7)](help://man/7/Mitigations) + +- [`pledge`(2)](help://man/2/pledge) +- [`unveil`(2)](help://man/2/unveil) +- [`Mitigations`(7)](help://man/7/Mitigations) diff --git a/Base/usr/share/man/man1/unzip.md b/Base/usr/share/man/man1/unzip.md index c15880e9d92..bd62397e197 100644 --- a/Base/usr/share/man/man1/unzip.md +++ b/Base/usr/share/man/man1/unzip.md @@ -14,12 +14,12 @@ unzip will extract files from a zip archive to the current directory. The program is compatible with the PKZIP file format specification. -The optional [files] argument can be used to only extract specific files within the archive (using wildcards) during the unzip process. A `_` can be used as a single-character wildcard, and `*` can be used as a variable-length wildcard. +The optional [files] argument can be used to only extract specific files within the archive (using wildcards) during the unzip process. A `_` can be used as a single-character wildcard, and `*` can be used as a variable-length wildcard. ## Options -* `-d path`, `--output-directory path`: Directory to receive the archive output -* `-q`, `--quiet`: Be less verbose +- `-d path`, `--output-directory path`: Directory to receive the archive output +- `-q`, `--quiet`: Be less verbose ## Examples @@ -39,5 +39,6 @@ Archive: archive.unzip ``` ## See also -* [`zip`(1)](help://man/1/zip) -* [`tar`(1)](help://man/1/tar) + +- [`zip`(1)](help://man/1/zip) +- [`tar`(1)](help://man/1/tar) diff --git a/Base/usr/share/man/man1/uptime.md b/Base/usr/share/man/man1/uptime.md index 9c038e04ca2..adb215176e0 100644 --- a/Base/usr/share/man/man1/uptime.md +++ b/Base/usr/share/man/man1/uptime.md @@ -15,8 +15,8 @@ This information includes when the system came online and how long it has been u ## Options -* `-p`, `--pretty`: Output only the uptime, in human-readable format. -* `-s`, `--since`: Output only the datetime when the system came online. +- `-p`, `--pretty`: Output only the uptime, in human-readable format. +- `-s`, `--since`: Output only the datetime when the system came online. ## Examples diff --git a/Base/usr/share/man/man1/utmpupdate.md b/Base/usr/share/man/man1/utmpupdate.md index 9c64fc0f5bc..e381c8c79da 100644 --- a/Base/usr/share/man/man1/utmpupdate.md +++ b/Base/usr/share/man/man1/utmpupdate.md @@ -10,14 +10,15 @@ $ utmpupdate [--create] [--delete] [--PID PID] [--from From] <tty> ## Options -* `-c`, `--create`: Create entry -* `-d`, `--delete`: Delete entry -* `-p PID`, `--PID PID`: PID -* `-f From`, `--from From`: From +- `-c`, `--create`: Create entry +- `-d`, `--delete`: Delete entry +- `-p PID`, `--PID PID`: PID +- `-f From`, `--from From`: From ## Arguments -* `tty`: TTY name +- `tty`: TTY name ## See also -* [`w`(1)](help://man/1/w) + +- [`w`(1)](help://man/1/w) diff --git a/Base/usr/share/man/man1/w.md b/Base/usr/share/man/man1/w.md index d863cd74686..ef08b961894 100644 --- a/Base/usr/share/man/man1/w.md +++ b/Base/usr/share/man/man1/w.md @@ -10,13 +10,14 @@ $ w [--no-header] [user] ## Options -* `-h`, `--no-header`: Don't show the header +- `-h`, `--no-header`: Don't show the header ## Arguments -* `user`: Only show information about the specified user +- `user`: Only show information about the specified user ## See also -* [`whoami`(1)](help://man/1/whoami) -* [`utmpupdate`(1)](help://man/1/utmpupdate) -* [`usermod`(8)](help://man/8/usermod) + +- [`whoami`(1)](help://man/1/whoami) +- [`utmpupdate`(1)](help://man/1/utmpupdate) +- [`usermod`(8)](help://man/8/usermod) diff --git a/Base/usr/share/man/man1/wallpaper.md b/Base/usr/share/man/man1/wallpaper.md index 0bcdbb2b4e4..4fc5672fcd6 100644 --- a/Base/usr/share/man/man1/wallpaper.md +++ b/Base/usr/share/man/man1/wallpaper.md @@ -15,9 +15,9 @@ list available wallpapers in the `/res/wallpapers/` directory. ## Options -* `-a`, `--show-all`: Show all wallpapers -* `-c`, `--show-current`: Show current wallpaper -* `-r`, `--set-random`: Set random wallpaper +- `-a`, `--show-all`: Show all wallpapers +- `-c`, `--show-current`: Show current wallpaper +- `-r`, `--set-random`: Set random wallpaper ## Examples diff --git a/Base/usr/share/man/man1/watch.md b/Base/usr/share/man/man1/watch.md index c0e8a4aa2f2..e351fe40bfd 100644 --- a/Base/usr/share/man/man1/watch.md +++ b/Base/usr/share/man/man1/watch.md @@ -15,15 +15,15 @@ aggregated error code. ## Options -* `-n seconds`: Interval between executions, in seconds. By default, the program is run every 2 seconds. -* `-t`, `--no-title`: Don't print the title bar. -* `-b`, `--beep`: Beep each time the command exits with a non-zero status. -* `-f file`, `--file file`: Run command whenever this file changes. Can be used multiple times. +- `-n seconds`: Interval between executions, in seconds. By default, the program is run every 2 seconds. +- `-t`, `--no-title`: Don't print the title bar. +- `-b`, `--beep`: Beep each time the command exits with a non-zero status. +- `-f file`, `--file file`: Run command whenever this file changes. Can be used multiple times. ## Exit Values -* 0 - Success -* 1 - At least one invocation of the command failed or exited with a non-zero status +- 0 - Success +- 1 - At least one invocation of the command failed or exited with a non-zero status ## Examples diff --git a/Base/usr/share/man/man1/watchfs.md b/Base/usr/share/man/man1/watchfs.md index 685e2ac9166..1bbf403b85b 100644 --- a/Base/usr/share/man/man1/watchfs.md +++ b/Base/usr/share/man/man1/watchfs.md @@ -14,18 +14,18 @@ $ watchfs [options...] [path...] ## Options -* `--help`: Display this message -* `-E`, `--exit-after-change`: Wait for first change and exit -* `-a`, `--watch-all-events`: Watch all types of events -* `-d`, `--watch-delete-events`: Watch file deletion events -* `-m`, `--watch-file-modify-events`: Watch file content being modified -* `-M`, `--watch-file-metadata-events`: Watch file metadata being modified -* `-c`, `--watch-directory-child-creation-events`: Watch directory child creation events -* `-D`, `--watch-directory-child-deletion-events`: Watch directory child deletion events +- `--help`: Display this message +- `-E`, `--exit-after-change`: Wait for first change and exit +- `-a`, `--watch-all-events`: Watch all types of events +- `-d`, `--watch-delete-events`: Watch file deletion events +- `-m`, `--watch-file-modify-events`: Watch file content being modified +- `-M`, `--watch-file-metadata-events`: Watch file metadata being modified +- `-c`, `--watch-directory-child-creation-events`: Watch directory child creation events +- `-D`, `--watch-directory-child-deletion-events`: Watch directory child deletion events ## Arguments -* `path`: Files and/or directories to watch +- `path`: Files and/or directories to watch ## Examples @@ -51,5 +51,6 @@ $ watchfs -m /tmp/test_file ``` ## See also -* [`listdir`(1)](help://man/1/listdir) to list directory entries -* [`ls`(1)](help://man/1/ls) to list directory contents + +- [`listdir`(1)](help://man/1/listdir) to list directory entries +- [`ls`(1)](help://man/1/ls) to list directory contents diff --git a/Base/usr/share/man/man1/wc.md b/Base/usr/share/man/man1/wc.md index 058a8a1a4e9..d8bd9272a78 100644 --- a/Base/usr/share/man/man1/wc.md +++ b/Base/usr/share/man/man1/wc.md @@ -10,15 +10,15 @@ $ wc [--lines] [--bytes] [--words] [--max-line-length] [file...] ## Options -* `--help`: Display help message and exit -* `--version`: Print version -* `-l`, `--lines`: Output line count -* `-c`, `--bytes`: Output byte count -* `-w`, `--words`: Output word count -* `-L`, `--max-line-length`: Output byte count of the longest line +- `--help`: Display help message and exit +- `--version`: Print version +- `-l`, `--lines`: Output line count +- `-c`, `--bytes`: Output byte count +- `-w`, `--words`: Output word count +- `-L`, `--max-line-length`: Output byte count of the longest line ## Arguments -* `file`: File to process +- `file`: File to process <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man1/which.md b/Base/usr/share/man/man1/which.md index 43792b7a489..4931076de19 100644 --- a/Base/usr/share/man/man1/which.md +++ b/Base/usr/share/man/man1/which.md @@ -14,8 +14,8 @@ $ which [options] executable ## Options -* `--help`: Display help message and exit -* `--version`: Print version +- `--help`: Display help message and exit +- `--version`: Print version ## Examples diff --git a/Base/usr/share/man/man1/whoami.md b/Base/usr/share/man/man1/whoami.md index b423d45abfb..6e8744d70ab 100644 --- a/Base/usr/share/man/man1/whoami.md +++ b/Base/usr/share/man/man1/whoami.md @@ -23,4 +23,4 @@ root ## See also -* [`id`(1)](help://man/1/id) +- [`id`(1)](help://man/1/id) diff --git a/Base/usr/share/man/man1/xargs.md b/Base/usr/share/man/man1/xargs.md index e8a39f7a501..eed97978957 100644 --- a/Base/usr/share/man/man1/xargs.md +++ b/Base/usr/share/man/man1/xargs.md @@ -18,24 +18,23 @@ It is to be noted that `command` is also subject to substitution in this mode. If no argument in `command` or `initial-arguments` contains the `placeholder`, an argument is added at the end of the list containing only the `placeholder`. - If a `placeholder` is not explicitly specified, no substitution will be performed, rather, the item(s) will be appended to the end of the command line, until either of the following conditions are met: -- Adding another argument would overflow the system maximum command length (or the provided `max-chars` limit) -- The number of lines used per command (`max-lines`) would be exceeded +- Adding another argument would overflow the system maximum command length (or the provided `max-chars` limit) +- The number of lines used per command (`max-lines`) would be exceeded `xargs` will read the items from standard input by default, and when data is read from standard input, the standard input of `command` is redirected to read from `/dev/null`. The standard input is left as-is if data is read from a file. ## Options -* `-I`, `--replace`: Set the `placeholder`, and force `max-lines` to 1 -* `-0`, `--null`: Split the items by zero bytes (null characters) instead of `delimiter` -* `-d`, `--delimiter`: Set the `delimiter`, which is a newline (`\n`) by default -* `-v`, `--verbose`: Display each expanded command on standard error before executing it -* `-a`, `--arg-file`: Read the items from the specified file, `-` refers to standard input and is the default -* `-L`, `--line-limit`: Set `max-lines`, `0` means unlimited (which is the default) -* `-s`, `--char-limit`: Set `max-chars`, which is `ARG_MAX` (the maximum command size supported by the system) by default +- `-I`, `--replace`: Set the `placeholder`, and force `max-lines` to 1 +- `-0`, `--null`: Split the items by zero bytes (null characters) instead of `delimiter` +- `-d`, `--delimiter`: Set the `delimiter`, which is a newline (`\n`) by default +- `-v`, `--verbose`: Display each expanded command on standard error before executing it +- `-a`, `--arg-file`: Read the items from the specified file, `-` refers to standard input and is the default +- `-L`, `--line-limit`: Set `max-lines`, `0` means unlimited (which is the default) +- `-s`, `--char-limit`: Set `max-chars`, which is `ARG_MAX` (the maximum command size supported by the system) by default ## Examples @@ -48,4 +47,4 @@ $ xargs -a stuff --null -s 1024 ## See also -* [`find`(1)](help://man/1/find) +- [`find`(1)](help://man/1/find) diff --git a/Base/usr/share/man/man1/yes.md b/Base/usr/share/man/man1/yes.md index 8d16ec4baba..84655459f6f 100644 --- a/Base/usr/share/man/man1/yes.md +++ b/Base/usr/share/man/man1/yes.md @@ -14,7 +14,7 @@ $ yes [string] ## Options -* `string`: String to print; defaults to "yes". +- `string`: String to print; defaults to "yes". ## Examples @@ -41,4 +41,5 @@ t^C ``` ## See also -* [`cat`(1)](help://man/1/cat) + +- [`cat`(1)](help://man/1/cat) diff --git a/Base/usr/share/man/man1/zip.md b/Base/usr/share/man/man1/zip.md index 410d0d0bd08..7cb11950ccc 100644 --- a/Base/usr/share/man/man1/zip.md +++ b/Base/usr/share/man/man1/zip.md @@ -16,8 +16,8 @@ The program is compatible with the PKZIP file format specification. ## Options -* `-r`, `--recurse-paths`: Travel the directory structure recursively -* `-f`, `--force`: Overwrite existing zip file +- `-r`, `--recurse-paths`: Travel the directory structure recursively +- `-f`, `--force`: Overwrite existing zip file ## Examples @@ -30,6 +30,7 @@ Archive: archive.zip ``` ## See also -* [`unzip`(1)](help://man/1/unzip) -* [`gzip`(1)](help://man/1/gzip) -* [`tar`(1)](help://man/1/tar) + +- [`unzip`(1)](help://man/1/unzip) +- [`gzip`(1)](help://man/1/gzip) +- [`tar`(1)](help://man/1/tar) diff --git a/Base/usr/share/man/man2/accept.md b/Base/usr/share/man/man2/accept.md index acc5e3c3d86..c3f4a4002ef 100644 --- a/Base/usr/share/man/man2/accept.md +++ b/Base/usr/share/man/man2/accept.md @@ -19,8 +19,9 @@ When `accept(2)` is successful, a new socket with a unique file descriptor is cr ## Return value If the return value is positive, it represents the file descriptor of the new socket connected to the client that was accepted. If the return value is -1, the error can be found in `errno`, where the most important errors are: -- `EBADFD`: The file descriptor `sockfd` is invalid. -- `ENOTSOCK`: The given file descriptor `sockfd` is valid, but does not point to a socket. -- `EMFILE`: No more file descriptors are available for the new socket. -- `EAGAIN`: The socket was specified to be non-blocking, and there is no client in the queue. The user should try to `accept(2)` again at a later point. -- `EINTR`: A signal interrupted the blocking. + +- `EBADFD`: The file descriptor `sockfd` is invalid. +- `ENOTSOCK`: The given file descriptor `sockfd` is valid, but does not point to a socket. +- `EMFILE`: No more file descriptors are available for the new socket. +- `EAGAIN`: The socket was specified to be non-blocking, and there is no client in the queue. The user should try to `accept(2)` again at a later point. +- `EINTR`: A signal interrupted the blocking. diff --git a/Base/usr/share/man/man2/access.md b/Base/usr/share/man/man2/access.md index 13d7b77027b..aadc0f37970 100644 --- a/Base/usr/share/man/man2/access.md +++ b/Base/usr/share/man/man2/access.md @@ -12,13 +12,14 @@ 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. +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. +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/adjtime.md b/Base/usr/share/man/man2/adjtime.md index 29b315426a8..79c4a2cf3c4 100644 --- a/Base/usr/share/man/man2/adjtime.md +++ b/Base/usr/share/man/man2/adjtime.md @@ -14,7 +14,7 @@ int adjtime(const struct timeval* delta, struct timeval* old_delta); `adjtime()` gradually increments the system time by `delta`, if it is non-null. -Serenity OS slows down or speeds up the system clock by at most 1%, so adjusting the time by N seconds takes 100 * n seconds to complete. +Serenity OS slows down or speeds up the system clock by at most 1%, so adjusting the time by N seconds takes 100 \* n seconds to complete. Calling `settimeofday()` or `clock_settime()` cancels in-progress time adjustments done by `adjtime`. @@ -28,6 +28,6 @@ In pledged programs, the `settime` promise is required when `delta` is not null. ## Errors -* `EFAULT`: `delta` and/or `old_delta` are not null and not in readable memory. -* `EINVAL`: `delta` is not null and has a `tv_nsec` field that's less than 0 or larger or equal to `10^6`. Negative deltas should have a negative `tv_sec` field but a `tv_nsec` that's larger or equal zero. For example, a delta of -0.5 s is represented by `{-1, 500'000}`. -* `EPERM`: `delta` is not null but geteuid() is not 0. +- `EFAULT`: `delta` and/or `old_delta` are not null and not in readable memory. +- `EINVAL`: `delta` is not null and has a `tv_nsec` field that's less than 0 or larger or equal to `10^6`. Negative deltas should have a negative `tv_sec` field but a `tv_nsec` that's larger or equal zero. For example, a delta of -0.5 s is represented by `{-1, 500'000}`. +- `EPERM`: `delta` is not null but geteuid() is not 0. diff --git a/Base/usr/share/man/man2/bindmount.md b/Base/usr/share/man/man2/bindmount.md index 17e9aa1a4f3..9f130953999 100644 --- a/Base/usr/share/man/man2/bindmount.md +++ b/Base/usr/share/man/man2/bindmount.md @@ -16,24 +16,24 @@ ErrorOr<void> bindmount(int source_fd, StringView target, int flags); The following `flags` are supported: -* `MS_NODEV`: Disallow opening any devices from this file system. -* `MS_NOEXEC`: Disallow executing any executables from this file system. -* `MS_NOSUID`: Ignore set-user-id bits on executables from this file system. -* `MS_RDONLY`: Mount the filesystem read-only. -* `MS_WXALLOWED`: Allow W^X protection circumvention for executables on this file system. -* `MS_AXALLOWED`: Allow anonymous executable mappings for executables on this file system. -* `MS_NOREGULAR`: Disallow opening any regular files from this file system. +- `MS_NODEV`: Disallow opening any devices from this file system. +- `MS_NOEXEC`: Disallow executing any executables from this file system. +- `MS_NOSUID`: Ignore set-user-id bits on executables from this file system. +- `MS_RDONLY`: Mount the filesystem read-only. +- `MS_WXALLOWED`: Allow W^X protection circumvention for executables on this file system. +- `MS_AXALLOWED`: Allow anonymous executable mappings for executables on this file system. +- `MS_NOREGULAR`: Disallow opening any regular files from this file system. These flags can be used as a security measure to limit the possible abuses of the mounted file system. ## Errors -* `EINVAL`: The `flags` value contains deprecated flags such as `MS_REMOUNT` or `MS_BIND`. -* `EPERM`: The current process does not have superuser privileges. -* `ENODEV`: The `source_fd` is not an open file descriptor to a valid filesystem inode. +- `EINVAL`: The `flags` value contains deprecated flags such as `MS_REMOUNT` or `MS_BIND`. +- `EPERM`: The current process does not have superuser privileges. +- `ENODEV`: The `source_fd` is not an open file descriptor to a valid filesystem inode. All of the usual path resolution errors may also occur. ## See also -* [`mount`(2)](help://man/2/mount) +- [`mount`(2)](help://man/2/mount) diff --git a/Base/usr/share/man/man2/disown.md b/Base/usr/share/man/man2/disown.md index 84160298653..94cd89ed9ce 100644 --- a/Base/usr/share/man/man2/disown.md +++ b/Base/usr/share/man/man2/disown.md @@ -20,6 +20,5 @@ In pledged programs, the `proc` promise is required for this system call. ## Errors -* `ESRCH`: No process with PID `pid` was found. -* `ECHILD`: The target process is not a child of the calling process. - +- `ESRCH`: No process with PID `pid` was found. +- `ECHILD`: The target process is not a child of the calling process. diff --git a/Base/usr/share/man/man2/futex.md b/Base/usr/share/man/man2/futex.md index bd07eb9e4f5..cda6295b144 100644 --- a/Base/usr/share/man/man2/futex.md +++ b/Base/usr/share/man/man2/futex.md @@ -22,16 +22,16 @@ essentially exposing the kernel's internal thread synchronization primitives to userspace. While the `futex()` API is powerful and generic, it is complex and cumbersome -to use, and notoriously tricky to use *correctly*. For this reason, it is not +to use, and notoriously tricky to use _correctly_. For this reason, it is not intended to be used by application code directly, but rather to serve as a building block for more specialized and easier to use synchronization primitives implemented in user space, such as mutexes and semaphores. Specifically, the `futex()` API is designed to enable userspace synchronization -primitives to have a *fast path* that does not involve calling into the kernel +primitives to have a _fast path_ that does not involve calling into the kernel at all in the common uncontended case, avoiding the cost of making a syscall completely. -*A futex* is a single 32-bit integer cell located anywhere in the address space +_A futex_ is a single 32-bit integer cell located anywhere in the address space of a process (identified by its address), as well as an associated kernel-side queue of waiting threads. The kernel-side resources associated with a futex are created and destroyed implicitly when a futex is used; in other words, any @@ -40,49 +40,50 @@ on which no threads are waiting is no different to any other integer. The kernel does not assign any meaning to the value of the futex integer; it is up to userspace to make use of the value for its own logic. -The `futex()` API provides a number of *operations*, the most basic ones being +The `futex()` API provides a number of _operations_, the most basic ones being _waiting_ and _waking_: -* `FUTEX_WAKE` / `futex_wake()`: wake up to `count` threads waiting on the - futex (in the raw `futex()` syscall, `count` is passed as the `value` - argument). The two most common values for `count` are 1 (wake a single - thread) and `UINT32_MAX` (wake all threads). -* `FUTEX_WAIT` / `futex_wait()`: wait on the futex, but only if the current - value of the futex integer matches the specified `value`. The value - comparison and blocking is done atomically: if another thread changes the - value before the calling thread starts waiting, the calling thread will not - begin waiting at all, and the `futex_wait()` call will return `EAGAIN` - immediately. A waiting thread may wake up spuriously, without a matching call - to `futex_wake()`. -* `FUTEX_WAKE_BITSET`: like `FUTEX_WAKE`, but only consider waiting threads - that have specified a matching bitset (passed in `value3`). Two bitsets match - if their *bitwise and* is non-zero. A thread that has not specified a bitset - is treated as having a bitset with all bits set (`FUTEX_BITSET_MATCH_ANY`, - equal to `0xffffffff`). -* `FUTEX_WAIT_BITSET`: like `FUTEX_WAIT`, but the thread will only get woken by - wake operations specifying a matching bitset. -* `FUTEX_REQUEUE`: wake up to `value` threads waiting on the futex, and requeue - up to `value2` (passed instead of the `timeout` argument) of the remaining - waiting threads to wait on another futex specified by `userspace_address2`, - without waking them up. Waking and requeueing threads is done atomically. +- `FUTEX_WAKE` / `futex_wake()`: wake up to `count` threads waiting on the + futex (in the raw `futex()` syscall, `count` is passed as the `value` + argument). The two most common values for `count` are 1 (wake a single + thread) and `UINT32_MAX` (wake all threads). +- `FUTEX_WAIT` / `futex_wait()`: wait on the futex, but only if the current + value of the futex integer matches the specified `value`. The value + comparison and blocking is done atomically: if another thread changes the + value before the calling thread starts waiting, the calling thread will not + begin waiting at all, and the `futex_wait()` call will return `EAGAIN` + immediately. A waiting thread may wake up spuriously, without a matching call + to `futex_wake()`. +- `FUTEX_WAKE_BITSET`: like `FUTEX_WAKE`, but only consider waiting threads + that have specified a matching bitset (passed in `value3`). Two bitsets match + if their _bitwise and_ is non-zero. A thread that has not specified a bitset + is treated as having a bitset with all bits set (`FUTEX_BITSET_MATCH_ANY`, + equal to `0xffffffff`). +- `FUTEX_WAIT_BITSET`: like `FUTEX_WAIT`, but the thread will only get woken by + wake operations specifying a matching bitset. +- `FUTEX_REQUEUE`: wake up to `value` threads waiting on the futex, and requeue + up to `value2` (passed instead of the `timeout` argument) of the remaining + waiting threads to wait on another futex specified by `userspace_address2`, + without waking them up. Waking and requeueing threads is done atomically. - Requeueing threads without waking them up is useful to avoid "thundering - herd" issues with synchronization primitives like condition variables, where - multiple threads may wait for an event, but an event can only be handled by a - single thread at a time. -* `FUTEX_CMP_REQUEUE`: like `FUTEX_REQUEUE`, but only if the current value of - the futex integer matches the specified `value3`. The value comparison, - waking and requeueing threads are all done atomically. -* `FUTEX_WAKE_OP`: modify the value of the futex specified by - `userspace_address2`, wake up to `value` threads waiting on the futex, and - optionally up to `value2` (passed instead of the `timeout` argument) threads - waiting on the futex specified by `userspace_address2`. + Requeueing threads without waking them up is useful to avoid "thundering + herd" issues with synchronization primitives like condition variables, where + multiple threads may wait for an event, but an event can only be handled by a + single thread at a time. - The details of this operation are not currently documented here, see the - implementation for details. +- `FUTEX_CMP_REQUEUE`: like `FUTEX_REQUEUE`, but only if the current value of + the futex integer matches the specified `value3`. The value comparison, + waking and requeueing threads are all done atomically. +- `FUTEX_WAKE_OP`: modify the value of the futex specified by + `userspace_address2`, wake up to `value` threads waiting on the futex, and + optionally up to `value2` (passed instead of the `timeout` argument) threads + waiting on the futex specified by `userspace_address2`. -Additionally, the `FUTEX_PRIVATE_FLAG` flag can be *or*'ed in with one of the -*operation* values listed above. This flag restricts the call to only work on + The details of this operation are not currently documented here, see the + implementation for details. + +Additionally, the `FUTEX_PRIVATE_FLAG` flag can be _or_'ed in with one of the +_operation_ values listed above. This flag restricts the call to only work on other threads of the same process (as opposed to any threads in the system that may have the same memory page mapped into their address space, possibly at a different address), which enables additional optimizations in the syscall @@ -91,29 +92,29 @@ argument in `futex_wait()` and `futex_wake()` wrapper functions. ## Return value -* `FUTEX_WAKE`, `FUTEX_WAKE_BITSET`, `FUTEX_WAKE_OP`: the number of the waiting - threads that have been woken up, which may be 0 or a positive number. -* `FUTEX_WAIT`, `FUTEX_WAIT_BITSET`: 0 if blocked and got woken up by an - explicit wake call or woke up spuriously, an error otherwise. -* `FUTEX_REQUEUE`, `FUTEX_CMP_REQUEUE`: the total number of threads woken up - and requeued. +- `FUTEX_WAKE`, `FUTEX_WAKE_BITSET`, `FUTEX_WAKE_OP`: the number of the waiting + threads that have been woken up, which may be 0 or a positive number. +- `FUTEX_WAIT`, `FUTEX_WAIT_BITSET`: 0 if blocked and got woken up by an + explicit wake call or woke up spuriously, an error otherwise. +- `FUTEX_REQUEUE`, `FUTEX_CMP_REQUEUE`: the total number of threads woken up + and requeued. ## Errors -* `EAGAIN`: for wait operations, did not begin waiting, because the futex value - has already been changed. -* `ETIMEDOUT`: for wait operations with a timeout, timed out. -* `EFAULT`: the specified futex address is invalid. -* `ENOSYS`: `FUTEX_CLOCK_REALTIME` was specified, but the operation is not - `FUTEX_WAIT` or `FUTEX_WAIT_BITSET`. -* `EINVAL`: The arithmetic-logical operation for `FUTEX_WAKE_OP` is invalid. +- `EAGAIN`: for wait operations, did not begin waiting, because the futex value + has already been changed. +- `ETIMEDOUT`: for wait operations with a timeout, timed out. +- `EFAULT`: the specified futex address is invalid. +- `ENOSYS`: `FUTEX_CLOCK_REALTIME` was specified, but the operation is not + `FUTEX_WAIT` or `FUTEX_WAIT_BITSET`. +- `EINVAL`: The arithmetic-logical operation for `FUTEX_WAKE_OP` is invalid. ## Examples The following program demonstrates how futexes can be used to implement a simple "event" synchronization primitive. An event has a boolean state: it can -be *set* or *unset*; the initial state being unset. The two operations on an -event are *waiting* until it is set, and *setting* it (which wakes up any +be _set_ or _unset_; the initial state being unset. The two operations on an +event are _waiting_ until it is set, and _setting_ it (which wakes up any threads that were waiting for the event to get set). Such a synchronization primitive could be used, for example, to notify threads @@ -180,14 +181,15 @@ The name "futex" stands for "fast userspace mutex". The `futex()` system call originally appeared in Linux. Since then, many other kernels implemented support for futex-like operations, under various names, in particular: -* Darwin (XNU) has private `ulock_wait()` and `ulock_wake()` API; -* Windows (NT) apparently has `WaitOnAddress()`, `WakeByAddressSingle()` and - `WakeByAddressAll()`; -* FreeBSD and DargonFly BSD have `umtx`; -* OpenBSD has Linux-like `futex()`; -* GNU Hurd has `gsync_wait()`, `gsync_wake()`, and `gsync_requeue()`. + +- Darwin (XNU) has private `ulock_wait()` and `ulock_wake()` API; +- Windows (NT) apparently has `WaitOnAddress()`, `WakeByAddressSingle()` and + `WakeByAddressAll()`; +- FreeBSD and DargonFly BSD have `umtx`; +- OpenBSD has Linux-like `futex()`; +- GNU Hurd has `gsync_wait()`, `gsync_wake()`, and `gsync_requeue()`. ## Further reading -* [Futexes Are Tricky](https://akkadia.org/drepper/futex.pdf) by Ulrich Drepper -* [Locking in WebKit](https://webkit.org/blog/6161/locking-in-webkit/) by Filip Pizlo +- [Futexes Are Tricky](https://akkadia.org/drepper/futex.pdf) by Ulrich Drepper +- [Locking in WebKit](https://webkit.org/blog/6161/locking-in-webkit/) by Filip Pizlo diff --git a/Base/usr/share/man/man2/get_process_name.md b/Base/usr/share/man/man2/get_process_name.md index 4d7ae0e4fa7..892b61129c2 100644 --- a/Base/usr/share/man/man2/get_process_name.md +++ b/Base/usr/share/man/man2/get_process_name.md @@ -1,6 +1,6 @@ ## Name -get\_process\_name - get the process name +get_process_name - get the process name ## Synopsis @@ -20,9 +20,9 @@ In pledged programs, the `stdio` promise is required for this system call. ## Errors -* `EFAULT`: the process name could not be copied into the buffer. -* `ENAMETOOLONG`: `buffer_length` is too short. +- `EFAULT`: the process name could not be copied into the buffer. +- `ENAMETOOLONG`: `buffer_length` is too short. ## See also -* [`set_process_name`(2)](help://man/2/set_process_name) +- [`set_process_name`(2)](help://man/2/set_process_name) diff --git a/Base/usr/share/man/man2/geteuid.md b/Base/usr/share/man/man2/geteuid.md index e8d117695e5..2e1f044f399 100644 --- a/Base/usr/share/man/man2/geteuid.md +++ b/Base/usr/share/man/man2/geteuid.md @@ -17,9 +17,9 @@ Returns the effective user or group id. ## See also -* [`setuid_overview`(7)](help://man/7/setuid_overview) -* [`getuid`(2) / `getgid`(2)](help://man/2/getuid) -* [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) -* [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) -* [`setuid`(2) / `setgid`(2)](help://man/2/setuid) -* [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) +- [`setuid_overview`(7)](help://man/7/setuid_overview) +- [`getuid`(2) / `getgid`(2)](help://man/2/getuid) +- [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) +- [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) +- [`setuid`(2) / `setgid`(2)](help://man/2/setuid) +- [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) diff --git a/Base/usr/share/man/man2/getpid.md b/Base/usr/share/man/man2/getpid.md index b266ab8f05e..bf651a00f18 100644 --- a/Base/usr/share/man/man2/getpid.md +++ b/Base/usr/share/man/man2/getpid.md @@ -24,5 +24,5 @@ None. ## See also -* [`getppid`(2)](help://man/2/getppid) -* [`gettid`(2)](help://man/2/gettid) +- [`getppid`(2)](help://man/2/getppid) +- [`gettid`(2)](help://man/2/gettid) diff --git a/Base/usr/share/man/man2/getppid.md b/Base/usr/share/man/man2/getppid.md index 181364192d1..71cd8a08c40 100644 --- a/Base/usr/share/man/man2/getppid.md +++ b/Base/usr/share/man/man2/getppid.md @@ -24,5 +24,5 @@ None. ## See also -* [`getpid`(2)](help://man/2/getpid) -* [`gettid`(2)](help://man/2/gettid) +- [`getpid`(2)](help://man/2/getpid) +- [`gettid`(2)](help://man/2/gettid) diff --git a/Base/usr/share/man/man2/getresuid.md b/Base/usr/share/man/man2/getresuid.md index 698d187aac4..a7b5f61caad 100644 --- a/Base/usr/share/man/man2/getresuid.md +++ b/Base/usr/share/man/man2/getresuid.md @@ -22,13 +22,13 @@ Otherwise, returns -1 and sets `errno` to describe the error. ## Errors -* `EFAULT`: One of the passed pointers is not valid, writeable pointer in the current process. +- `EFAULT`: One of the passed pointers is not valid, writeable pointer in the current process. ## See also -* [`setuid_overview`(7)](help://man/7/setuid_overview) -* [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) -* [`getuid`(2) / `getgid`(2)](help://man/2/getuid) -* [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) -* [`setuid`(2) / `setgid`(2)](help://man/2/setuid) -* [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) +- [`setuid_overview`(7)](help://man/7/setuid_overview) +- [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) +- [`getuid`(2) / `getgid`(2)](help://man/2/getuid) +- [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) +- [`setuid`(2) / `setgid`(2)](help://man/2/setuid) +- [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) diff --git a/Base/usr/share/man/man2/gettid.md b/Base/usr/share/man/man2/gettid.md index 0f9ab49eddf..0ea2c29512a 100644 --- a/Base/usr/share/man/man2/gettid.md +++ b/Base/usr/share/man/man2/gettid.md @@ -24,5 +24,5 @@ None. ## See also -* [`getpid`(2)](help://man/2/getpid) -* [`getppid`(2)](help://man/2/getppid) +- [`getpid`(2)](help://man/2/getpid) +- [`getppid`(2)](help://man/2/getppid) diff --git a/Base/usr/share/man/man2/getuid.md b/Base/usr/share/man/man2/getuid.md index fa7ca8f7833..63235d13c52 100644 --- a/Base/usr/share/man/man2/getuid.md +++ b/Base/usr/share/man/man2/getuid.md @@ -17,9 +17,9 @@ Returns the real user or group id. ## See also -* [`setuid_overview`(7)](help://man/7/setuid_overview) -* [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) -* [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) -* [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) -* [`setuid`(2) / `setgid`(2)](help://man/2/setuid) -* [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) +- [`setuid_overview`(7)](help://man/7/setuid_overview) +- [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) +- [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) +- [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) +- [`setuid`(2) / `setgid`(2)](help://man/2/setuid) +- [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) diff --git a/Base/usr/share/man/man2/mkdir.md b/Base/usr/share/man/man2/mkdir.md index 293b13d3fec..fc3a08d878f 100644 --- a/Base/usr/share/man/man2/mkdir.md +++ b/Base/usr/share/man/man2/mkdir.md @@ -12,7 +12,7 @@ int mkdir(const char* path, mode_t mode); ## Description -Create a new empty directory at the given *path* using the given *mode*. +Create a new empty directory at the given _path_ using the given _mode_. ## Return value @@ -21,4 +21,4 @@ it returns -1 and sets `errno` to describe the error. ## See also -* [`mkdir`(1)](help://man/1/mkdir) +- [`mkdir`(1)](help://man/1/mkdir) diff --git a/Base/usr/share/man/man2/mount.md b/Base/usr/share/man/man2/mount.md index b15b4fc8701..d11d4c604ee 100644 --- a/Base/usr/share/man/man2/mount.md +++ b/Base/usr/share/man/man2/mount.md @@ -17,11 +17,11 @@ over `target`. `fs_type` must be one of the following supported filesystems: -* `Ext2FS` (or `ext2`): The ext2 filesystem. -* `ProcFS` (or `proc`): The process pseudo-filesystem (normally mounted at `/proc`). -* `DevPtsFS` (or `devpts`): The pseudoterminal pseudo-filesystem (normally mounted at `/dev/pts`). -* `RAMFS` (or `ram`): A non-persistent filesystem that stores all its data in RAM. An instance of this filesystem is normally mounted at `/tmp`. -* `Plan9FS` (or `9p`): A remote filesystem served over the 9P protocol. +- `Ext2FS` (or `ext2`): The ext2 filesystem. +- `ProcFS` (or `proc`): The process pseudo-filesystem (normally mounted at `/proc`). +- `DevPtsFS` (or `devpts`): The pseudoterminal pseudo-filesystem (normally mounted at `/dev/pts`). +- `RAMFS` (or `ram`): A non-persistent filesystem that stores all its data in RAM. An instance of this filesystem is normally mounted at `/tmp`. +- `Plan9FS` (or `9p`): A remote filesystem served over the 9P protocol. For Ext2FS, `source_fd` must refer to an open file descriptor to a file containing the filesystem image. This may be a device file or any other seekable @@ -31,13 +31,13 @@ an invalid file descriptor such as -1. The following `flags` are supported: -* `MS_NODEV`: Disallow opening any devices from this file system. -* `MS_NOEXEC`: Disallow executing any executables from this file system. -* `MS_NOSUID`: Ignore set-user-id bits on executables from this file system. -* `MS_RDONLY`: Mount the filesystem read-only. -* `MS_WXALLOWED`: Allow W^X protection circumvention for executables on this file system. -* `MS_AXALLOWED`: Allow anonymous executable mappings for executables on this file system. -* `MS_NOREGULAR`: Disallow opening any regular files from this file system. +- `MS_NODEV`: Disallow opening any devices from this file system. +- `MS_NOEXEC`: Disallow executing any executables from this file system. +- `MS_NOSUID`: Ignore set-user-id bits on executables from this file system. +- `MS_RDONLY`: Mount the filesystem read-only. +- `MS_WXALLOWED`: Allow W^X protection circumvention for executables on this file system. +- `MS_AXALLOWED`: Allow anonymous executable mappings for executables on this file system. +- `MS_NOREGULAR`: Disallow opening any regular files from this file system. These flags can be used as a security measure to limit the possible abuses of the newly mounted file system. @@ -69,23 +69,23 @@ to use the new mount flags after remounting a filesystem, a process can call ## Errors -* `EINVAL`: The `flags` value contains deprecated flags such as `MS_REMOUNT` or `MS_BIND`. -* `EFAULT`: The `fs_type` or `target` are invalid strings. -* `EPERM`: The current process does not have superuser privileges. -* `ENODEV`: The `fs_type` is unrecognized, or the file descriptor to source is - not found, or the source doesn't contain a valid filesystem image. Also, this - error occurs if `fs_type` is valid and required to be seekable, but the file - descriptor from `source_fd` is not seekable. -* `EBADF`: If the `source_fd` is not valid, and either `fs_type` specifies a - file-backed filesystem (and not a pseudo filesystem), or `MS_BIND` is - specified in flags. -* `ENOTBLK`: If the `source_fd` is not a block device, but one is required (i.e. - when `fs_type` is `Ext2FS`) +- `EINVAL`: The `flags` value contains deprecated flags such as `MS_REMOUNT` or `MS_BIND`. +- `EFAULT`: The `fs_type` or `target` are invalid strings. +- `EPERM`: The current process does not have superuser privileges. +- `ENODEV`: The `fs_type` is unrecognized, or the file descriptor to source is + not found, or the source doesn't contain a valid filesystem image. Also, this + error occurs if `fs_type` is valid and required to be seekable, but the file + descriptor from `source_fd` is not seekable. +- `EBADF`: If the `source_fd` is not valid, and either `fs_type` specifies a + file-backed filesystem (and not a pseudo filesystem), or `MS_BIND` is + specified in flags. +- `ENOTBLK`: If the `source_fd` is not a block device, but one is required (i.e. + when `fs_type` is `Ext2FS`) All of the usual path resolution errors may also occur. ## See also -* [`mount`(8)](help://man/8/mount) -* [`remount`(2)](help://man/2/remount) -* [`bindmount`(2)](help://man/2/bindmount) +- [`mount`(8)](help://man/8/mount) +- [`remount`(2)](help://man/2/remount) +- [`bindmount`(2)](help://man/2/bindmount) diff --git a/Base/usr/share/man/man2/pipe.md b/Base/usr/share/man/man2/pipe.md index c569f4e81ee..591afa24f57 100644 --- a/Base/usr/share/man/man2/pipe.md +++ b/Base/usr/share/man/man2/pipe.md @@ -17,9 +17,9 @@ int pipe2(int pipefd[2], int flags); 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*: +`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()`. +- `O_CLOEXEC`: Automatically close the file descriptors created by this call, as if by `close()` call, when performing an `exec()`. ## Examples diff --git a/Base/usr/share/man/man2/pledge.md b/Base/usr/share/man/man2/pledge.md index ce76fd57c60..bb4fdd6415b 100644 --- a/Base/usr/share/man/man2/pledge.md +++ b/Base/usr/share/man/man2/pledge.md @@ -24,48 +24,48 @@ Note that `pledge()` can be called repeatedly to remove previously-pledged promi If `promises` or `execpromises` is null, the corresponding value is unchanged. -If the process later attempts to use any system functionality it has previously promised *not* to use, the process is instantly terminated. Note that a process that has not ever called `pledge()` is considered to not have made any promises, and is allowed use any system functionality (subject to regular permission checks). +If the process later attempts to use any system functionality it has previously promised _not_ to use, the process is instantly terminated. Note that a process that has not ever called `pledge()` is considered to not have made any promises, and is allowed use any system functionality (subject to regular permission checks). `pledge()` is intended to be used in programs that want to sandbox themselves, either to limit the impact of a possible vulnerability exploitation, or before intentionally executing untrusted code. ## Promises -* `stdio`: Basic I/O, memory allocation, information about self, various non-destructive syscalls -* `thread`: The POSIX threading API (\*) -* `id`: Ability to change UID/GID -* `tty`: TTY related functionality -* `proc`: Process and scheduling related functionality -* `exec`: The [`exec`(2)](help://man/2/exec) syscall -* `unix`: UNIX local domain sockets -* `inet`: IPv4 domain sockets -* `accept`: May use [`accept`(2)](help://man/2/accept) to accept incoming socket connections on already listening sockets (\*) -* `rpath`: "Read" filesystem access -* `wpath`: "Write" filesystem access -* `cpath`: "Create" filesystem access -* `dpath`: Creating new device files -* `chown`: Changing file owner/group -* `fattr`: Changing file attributes/permissions -* `video`: May use [`ioctl`(2)](help://man/2/ioctl) and [`mmap`(2)](help://man/2/mmap) on framebuffer video devices -* `settime`: Changing the system time and date -* `setkeymap`: Changing the system keyboard layout (\*) -* `sigaction`: Change signal handlers and dispositions (\*) -* `sendfd`: Send file descriptors over a local socket -* `recvfd`: Receive file descriptors over a local socket -* `ptrace`: The [`ptrace`(2)](help://man/2/ptrace) syscall (\*) -* `prot_exec`: [`mmap`(2)](help://man/2/mmap) and [`mprotect`(2)](help://man/2/mprotect) with `PROT_EXEC` -* `map_fixed`: [`mmap`(2)](help://man/2/mmap) with `MAP_FIXED` or `MAP_FIXED_NOREPLACE` (\*) -* `mount`: [`mount`(2)](help://man/2/mount) Various filesystem mount related syscalls (\*) -* `unshare`: Various unshare-specific syscalls (\*) -* `no_error`: Ignore requests of pledge elevation going forwards, this is useful for enforcing _execpromises_ while the child process wants to ask for more upfront (Note that the elevation requests are _not_ granted, merely ignored), this is similar to the `error` pledge in OpenBSD. +- `stdio`: Basic I/O, memory allocation, information about self, various non-destructive syscalls +- `thread`: The POSIX threading API (\*) +- `id`: Ability to change UID/GID +- `tty`: TTY related functionality +- `proc`: Process and scheduling related functionality +- `exec`: The [`exec`(2)](help://man/2/exec) syscall +- `unix`: UNIX local domain sockets +- `inet`: IPv4 domain sockets +- `accept`: May use [`accept`(2)](help://man/2/accept) to accept incoming socket connections on already listening sockets (\*) +- `rpath`: "Read" filesystem access +- `wpath`: "Write" filesystem access +- `cpath`: "Create" filesystem access +- `dpath`: Creating new device files +- `chown`: Changing file owner/group +- `fattr`: Changing file attributes/permissions +- `video`: May use [`ioctl`(2)](help://man/2/ioctl) and [`mmap`(2)](help://man/2/mmap) on framebuffer video devices +- `settime`: Changing the system time and date +- `setkeymap`: Changing the system keyboard layout (\*) +- `sigaction`: Change signal handlers and dispositions (\*) +- `sendfd`: Send file descriptors over a local socket +- `recvfd`: Receive file descriptors over a local socket +- `ptrace`: The [`ptrace`(2)](help://man/2/ptrace) syscall (\*) +- `prot_exec`: [`mmap`(2)](help://man/2/mmap) and [`mprotect`(2)](help://man/2/mprotect) with `PROT_EXEC` +- `map_fixed`: [`mmap`(2)](help://man/2/mmap) with `MAP_FIXED` or `MAP_FIXED_NOREPLACE` (\*) +- `mount`: [`mount`(2)](help://man/2/mount) Various filesystem mount related syscalls (\*) +- `unshare`: Various unshare-specific syscalls (\*) +- `no_error`: Ignore requests of pledge elevation going forwards, this is useful for enforcing _execpromises_ while the child process wants to ask for more upfront (Note that the elevation requests are _not_ granted, merely ignored), this is similar to the `error` pledge in OpenBSD. Promises marked with an asterisk (\*) are SerenityOS specific extensions not supported by the original OpenBSD `pledge()`. ## Errors -* `EFAULT`: `promises` and/or `execpromises` are not null and not in readable memory. -* `EINVAL`: One or more invalid promises were specified. -* `EPERM`: An attempt to increase capabilities was rejected. -* `E2BIG`: `promises` string or `execpromises `string are longer than all known promises strings together. +- `EFAULT`: `promises` and/or `execpromises` are not null and not in readable memory. +- `EINVAL`: One or more invalid promises were specified. +- `EPERM`: An attempt to increase capabilities was rejected. +- `E2BIG`: `promises` string or `execpromises `string are longer than all known promises strings together. ## History @@ -73,5 +73,5 @@ The `pledge()` system call was first introduced by OpenBSD. The implementation i ## See also -* [`unveil`(2)](help://man/2/unveil) -* [`Mitigations`(7)](help://man/7/Mitigations) +- [`unveil`(2)](help://man/2/unveil) +- [`Mitigations`(7)](help://man/7/Mitigations) diff --git a/Base/usr/share/man/man2/readlink.md b/Base/usr/share/man/man2/readlink.md index 6f4b9b6c94b..ac098d79a27 100644 --- a/Base/usr/share/man/man2/readlink.md +++ b/Base/usr/share/man/man2/readlink.md @@ -64,4 +64,4 @@ ErrorOr<pid_t> read_pid_using_core_file() ## See also -* [`readlink`(1)](help://man/1/readlink) +- [`readlink`(1)](help://man/1/readlink) diff --git a/Base/usr/share/man/man2/recvfd.md b/Base/usr/share/man/man2/recvfd.md index bd13777d69f..cf46c3b8fbe 100644 --- a/Base/usr/share/man/man2/recvfd.md +++ b/Base/usr/share/man/man2/recvfd.md @@ -16,9 +16,9 @@ Receive an open file descriptor from a local socket peer connected via `sockfd`. File descriptors are sent out-of-band and do not affect the regular data streams. -The *options* argument accepts a bitmask of the following flags: +The _options_ argument accepts a bitmask of the following flags: -* `O_CLOEXEC`: The opened fd shall be closed on [`exec`(2)](help://man/2/exec). +- `O_CLOEXEC`: The opened fd shall be closed on [`exec`(2)](help://man/2/exec). ## Return value @@ -26,11 +26,11 @@ If a file descriptor is successfully received, it is returned as a non-negative ## Errors -* `EBADF`: `sockfd` is not an open file descriptor. -* `ENOTSOCK`: `sockfd` does not refer to a socket. -* `EAFNOSUPPORT`: `sockfd` does not refer to a local domain socket. -* `EINVAL`: `sockfd` does not refer to a connected or accepted socket. -* `EAGAIN`: There is no file descriptor queued on this socket. +- `EBADF`: `sockfd` is not an open file descriptor. +- `ENOTSOCK`: `sockfd` does not refer to a socket. +- `EAFNOSUPPORT`: `sockfd` does not refer to a local domain socket. +- `EINVAL`: `sockfd` does not refer to a connected or accepted socket. +- `EAGAIN`: There is no file descriptor queued on this socket. ## History @@ -38,4 +38,4 @@ If a file descriptor is successfully received, it is returned as a non-negative ## See also -* [`sendfd`(2)](help://man/2/sendfd) +- [`sendfd`(2)](help://man/2/sendfd) diff --git a/Base/usr/share/man/man2/remount.md b/Base/usr/share/man/man2/remount.md index d4384caaf3b..0959c9e71e4 100644 --- a/Base/usr/share/man/man2/remount.md +++ b/Base/usr/share/man/man2/remount.md @@ -16,24 +16,24 @@ ErrorOr<void> remount(StringView target, int flags); The following `flags` are supported: -* `MS_NODEV`: Disallow opening any devices from this file system. -* `MS_NOEXEC`: Disallow executing any executables from this file system. -* `MS_NOSUID`: Ignore set-user-id bits on executables from this file system. -* `MS_RDONLY`: Mount the filesystem read-only. -* `MS_WXALLOWED`: Allow W^X protection circumvention for executables on this file system. -* `MS_AXALLOWED`: Allow anonymous executable mappings for executables on this file system. -* `MS_NOREGULAR`: Disallow opening any regular files from this file system. +- `MS_NODEV`: Disallow opening any devices from this file system. +- `MS_NOEXEC`: Disallow executing any executables from this file system. +- `MS_NOSUID`: Ignore set-user-id bits on executables from this file system. +- `MS_RDONLY`: Mount the filesystem read-only. +- `MS_WXALLOWED`: Allow W^X protection circumvention for executables on this file system. +- `MS_AXALLOWED`: Allow anonymous executable mappings for executables on this file system. +- `MS_NOREGULAR`: Disallow opening any regular files from this file system. These flags can be used as a security measure to limit the possible abuses of the mounted file system. ## Errors -* `EINVAL`: The `flags` value contains deprecated flags such as `MS_REMOUNT` or `MS_BIND`. -* `EPERM`: The current process does not have superuser privileges. -* `ENODEV`: No mount point was found for `target` path target. +- `EINVAL`: The `flags` value contains deprecated flags such as `MS_REMOUNT` or `MS_BIND`. +- `EPERM`: The current process does not have superuser privileges. +- `ENODEV`: No mount point was found for `target` path target. All of the usual path resolution errors may also occur. ## See also -* [`mount`(2)](help://man/2/mount) +- [`mount`(2)](help://man/2/mount) diff --git a/Base/usr/share/man/man2/scheduler_set_parameters.md b/Base/usr/share/man/man2/scheduler_set_parameters.md index 22d44365995..cc3a274cc79 100644 --- a/Base/usr/share/man/man2/scheduler_set_parameters.md +++ b/Base/usr/share/man/man2/scheduler_set_parameters.md @@ -7,6 +7,7 @@ scheduler_set_parameters, scheduler_get_parameters - Set and get scheduler param Modify or retrieve the scheduler parameters for processes or threads. `scheduler_set_parameters` will affect how the process or thread specified is scheduled the next time, so it might not have an immediately observable effect. The parameter argument given to both system calls is defined as: + ```**c++ struct SC_scheduler_parameters_params { pid_t pid_or_tid; @@ -15,9 +16,9 @@ struct SC_scheduler_parameters_params { }; ``` -- `mode` is an enum taking the values `Process` and `Thread`. It specifies whether the syscalls handle whole-process scheduler parameters or thread-level scheduler parameters. -- `pid_or_tid` specifies the process or thread to operate on, depending on `mode`. -- `sched_param` is the parameters that are to be read or written for the process or thread specified with the other parameters. This struct is the POSIX-compliant data structure used in `sched_setparam` and others. +- `mode` is an enum taking the values `Process` and `Thread`. It specifies whether the syscalls handle whole-process scheduler parameters or thread-level scheduler parameters. +- `pid_or_tid` specifies the process or thread to operate on, depending on `mode`. +- `sched_param` is the parameters that are to be read or written for the process or thread specified with the other parameters. This struct is the POSIX-compliant data structure used in `sched_setparam` and others. The only currently available scheduling parameter is the `int sched_priority`, the scheduling priority. @@ -26,9 +27,10 @@ The only currently available scheduling parameter is the `int sched_priority`, t Both system calls require the `proc` promise. There are the following limitations as to which process can modify which process' or thread's parameters: -- The superuser can modify any process or thread scheduling parameters. -- Any thread can modify the scheduling parameters of all of its process' threads and of the process itself. -- Any process can modify the scheduling parameters of all processes that are owned by the same user (effective user ID and user ID must match). It cannot, however, modify the scheduling parameters of individual threads within the process. + +- The superuser can modify any process or thread scheduling parameters. +- Any thread can modify the scheduling parameters of all of its process' threads and of the process itself. +- Any process can modify the scheduling parameters of all processes that are owned by the same user (effective user ID and user ID must match). It cannot, however, modify the scheduling parameters of individual threads within the process. ## Return value @@ -36,10 +38,10 @@ For `scheduler_get_parameters`, the retrieved parameters are written into the `s ## Errors -* `EINVAL`: The scheduling parameters are invalid. -* `EPERM`: The thread is not allowed to access the scheduling parameters for the given process or thread. -* `ESRC`: The given process ID or thread ID does not refer to an existing process or thread. -* `EFAULT`: The parameter structure pointer is invalid. +- `EINVAL`: The scheduling parameters are invalid. +- `EPERM`: The thread is not allowed to access the scheduling parameters for the given process or thread. +- `ESRC`: The given process ID or thread ID does not refer to an existing process or thread. +- `EFAULT`: The parameter structure pointer is invalid. ## History diff --git a/Base/usr/share/man/man2/sendfd.md b/Base/usr/share/man/man2/sendfd.md index 99cac793e6f..3d38e365bc4 100644 --- a/Base/usr/share/man/man2/sendfd.md +++ b/Base/usr/share/man/man2/sendfd.md @@ -22,12 +22,12 @@ If a file descriptor is successfully sent, `sendfd()` returns 0. Otherwise, -1 i ## Errors -* `EBADF`: `sockfd` or `fd` is not an open file descriptor. -* `ENOTSOCK`: `sockfd` does not refer to a socket. -* `EAFNOSUPPORT`: `sockfd` does not refer to a local domain socket. -* `ENOTCONN`: `sockfd` refers to a socket which is not connected. -* `EINVAL`: `sockfd` does not refer to a connected or accepted socket. -* `EBUSY`: There are too many file descriptors already waiting to be received by the peer. +- `EBADF`: `sockfd` or `fd` is not an open file descriptor. +- `ENOTSOCK`: `sockfd` does not refer to a socket. +- `EAFNOSUPPORT`: `sockfd` does not refer to a local domain socket. +- `ENOTCONN`: `sockfd` refers to a socket which is not connected. +- `EINVAL`: `sockfd` does not refer to a connected or accepted socket. +- `EBUSY`: There are too many file descriptors already waiting to be received by the peer. ## History @@ -35,4 +35,4 @@ If a file descriptor is successfully sent, `sendfd()` returns 0. Otherwise, -1 i ## See also -* [`recvfd`(2)](help://man/2/recvfd) +- [`recvfd`(2)](help://man/2/recvfd) diff --git a/Base/usr/share/man/man2/set_process_name.md b/Base/usr/share/man/man2/set_process_name.md index e6589c09397..484929ced55 100644 --- a/Base/usr/share/man/man2/set_process_name.md +++ b/Base/usr/share/man/man2/set_process_name.md @@ -1,6 +1,6 @@ ## Name -set\_process\_name - change the process name +set_process_name - change the process name ## Synopsis @@ -20,9 +20,9 @@ In pledged programs, the `proc` promise is required for this system call. ## Errors -* `EFAULT`: `name` is not in readable memory. -* `ENAMETOOLONG`: `name_length` is too long. +- `EFAULT`: `name` is not in readable memory. +- `ENAMETOOLONG`: `name_length` is too long. ## See also -* [`get_process_name`(2)](help://man/2/get_process_name) +- [`get_process_name`(2)](help://man/2/get_process_name) diff --git a/Base/usr/share/man/man2/seteuid.md b/Base/usr/share/man/man2/seteuid.md index 912652af6b1..b628cf24e92 100644 --- a/Base/usr/share/man/man2/seteuid.md +++ b/Base/usr/share/man/man2/seteuid.md @@ -26,14 +26,14 @@ Otherwise, returns -1 and sets `errno` to describe the error. ## Errors -* `EPERM`: The new ID is not equal to the real ID or saved ID, and the user is not superuser. -* `EINVAL`: The new ID is set to invalid value (-1). +- `EPERM`: The new ID is not equal to the real ID or saved ID, and the user is not superuser. +- `EINVAL`: The new ID is set to invalid value (-1). ## See also -* [`setuid_overview`(7)](help://man/7/setuid_overview) -* [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) -* [`getuid`(2) / `getgid`(2)](help://man/2/getuid) -* [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) -* [`setuid`(2) / `setgid`(2)](help://man/2/setuid) -* [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) +- [`setuid_overview`(7)](help://man/7/setuid_overview) +- [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) +- [`getuid`(2) / `getgid`(2)](help://man/2/getuid) +- [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) +- [`setuid`(2) / `setgid`(2)](help://man/2/setuid) +- [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) diff --git a/Base/usr/share/man/man2/setresuid.md b/Base/usr/share/man/man2/setresuid.md index d83b2b807e4..cff38faad8d 100644 --- a/Base/usr/share/man/man2/setresuid.md +++ b/Base/usr/share/man/man2/setresuid.md @@ -26,13 +26,13 @@ Otherwise, returns -1 and sets `errno` to describe the error. ## Errors -* `EPERM`: At least one of the passed IDs was not equal to the current real, effective, or saved ID, and the user is not superuser. +- `EPERM`: At least one of the passed IDs was not equal to the current real, effective, or saved ID, and the user is not superuser. ## See also -* [`setuid_overview`(7)](help://man/7/setuid_overview) -* [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) -* [`getuid`(2) / `getgid`(2)](help://man/2/getuid) -* [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) -* [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) -* [`setuid`(2) / `setgid`(2)](help://man/2/setuid) +- [`setuid_overview`(7)](help://man/7/setuid_overview) +- [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) +- [`getuid`(2) / `getgid`(2)](help://man/2/getuid) +- [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) +- [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) +- [`setuid`(2) / `setgid`(2)](help://man/2/setuid) diff --git a/Base/usr/share/man/man2/setuid.md b/Base/usr/share/man/man2/setuid.md index 44c27b52f4e..038ec2cdf4e 100644 --- a/Base/usr/share/man/man2/setuid.md +++ b/Base/usr/share/man/man2/setuid.md @@ -24,14 +24,14 @@ Otherwise, returns -1 and sets `errno` to describe the error. ## Errors -* `EPERM`: The new ID is not equal to the real ID or effective ID, and the user is not superuser. -* `EINVAL`: The new ID is set to invalid value (-1). +- `EPERM`: The new ID is not equal to the real ID or effective ID, and the user is not superuser. +- `EINVAL`: The new ID is set to invalid value (-1). ## See also -* [`setuid_overview`(7)](help://man/7/setuid_overview) -* [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) -* [`getuid`(2) / `getgid`(2)](help://man/2/getuid) -* [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) -* [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) -* [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) +- [`setuid_overview`(7)](help://man/7/setuid_overview) +- [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) +- [`getuid`(2) / `getgid`(2)](help://man/2/getuid) +- [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) +- [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) +- [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) diff --git a/Base/usr/share/man/man2/uname.md b/Base/usr/share/man/man2/uname.md index 61da6b3bbd5..9f873e99f29 100644 --- a/Base/usr/share/man/man2/uname.md +++ b/Base/usr/share/man/man2/uname.md @@ -31,8 +31,8 @@ If successful, returns 0. Otherwise, returns -1 and sets `errno` to describe the ## Errors -* `EFAULT`: `buf` is not a writable address. +- `EFAULT`: `buf` is not a writable address. ## See also -* [`uname`(1)](help://man/1/uname) +- [`uname`(1)](help://man/1/uname) diff --git a/Base/usr/share/man/man2/unveil.md b/Base/usr/share/man/man2/unveil.md index 2afbd9b3899..6e00b3f8c1d 100644 --- a/Base/usr/share/man/man2/unveil.md +++ b/Base/usr/share/man/man2/unveil.md @@ -24,11 +24,11 @@ Calling `unveil()` allows the process to access the given `path`, which must be an absolute path, according to the given `permissions` string, which may include the following characters: -* `r`: May read a file at this path -* `w`: May write to a file at this path -* `x`: May execute a program image at this path -* `c`: May create or remove a file at this path -* `b`: May browse directories at this path +- `r`: May read a file at this path +- `w`: May write to a file at this path +- `x`: May execute a program image at this path +- `c`: May create or remove a file at this path +- `b`: May browse directories at this path A single `unveil()` call may specify multiple permission characters at once. Subsequent `unveil()` calls may take away permissions from the ones allowed @@ -63,12 +63,12 @@ the error. ## Errors -* `EFAULT`: `path` and/or `permissions` are not null and not in readable - memory. -* `EPERM`: The veil is locked, or an attempt to add more permissions for an - already unveiled path was rejected. -* `EINVAL`: `path` is not an absolute path, or `permissions` are malformed. -* `E2BIG`: `permissions` string is longer than 5 characters. +- `EFAULT`: `path` and/or `permissions` are not null and not in readable + memory. +- `EPERM`: The veil is locked, or an attempt to add more permissions for an + already unveiled path was rejected. +- `EINVAL`: `path` is not an absolute path, or `permissions` are malformed. +- `E2BIG`: `permissions` string is longer than 5 characters. All of the usual path resolution errors may also occur. @@ -97,6 +97,6 @@ unveil(nullptr, nullptr); ## See also -* [`unveil`(1)](help://man/1/unveil) -* [`pledge`(2)](help://man/2/pledge) -* [`Mitigations`(7)](help://man/7/Mitigations) +- [`unveil`(1)](help://man/1/unveil) +- [`pledge`(2)](help://man/2/pledge) +- [`Mitigations`(7)](help://man/7/Mitigations) diff --git a/Base/usr/share/man/man3/basename.md b/Base/usr/share/man/man3/basename.md index 6ee64ffe865..c71a67f9601 100644 --- a/Base/usr/share/man/man3/basename.md +++ b/Base/usr/share/man/man3/basename.md @@ -50,4 +50,4 @@ int main() ## See also -* [`dirname`(3)](help://man/3/dirname) +- [`dirname`(3)](help://man/3/dirname) diff --git a/Base/usr/share/man/man3/dirname.md b/Base/usr/share/man/man3/dirname.md index 2001e165f22..6b7acb183fa 100644 --- a/Base/usr/share/man/man3/dirname.md +++ b/Base/usr/share/man/man3/dirname.md @@ -51,4 +51,4 @@ int main() ## See also -* [`basename`(3)](help://man/3/basename) +- [`basename`(3)](help://man/3/basename) diff --git a/Base/usr/share/man/man3/getopt.md b/Base/usr/share/man/man3/getopt.md index 88625e7084e..a853b3a8544 100644 --- a/Base/usr/share/man/man3/getopt.md +++ b/Base/usr/share/man/man3/getopt.md @@ -46,9 +46,9 @@ to be recognized. To specify whether a long option has a value, the `has_arg` member of `struct option` must be set to one of the following predefined macro values: -* `no_argument`, if no value is accepted; -* `required_argument`, if a value is optionally accepted; -* `optional_argument`, if a value is optionally accepted. +- `no_argument`, if no value is accepted; +- `required_argument`, if a value is optionally accepted; +- `optional_argument`, if a value is optionally accepted. If an option is parsed successfully, `getopt()` and `getopt_long()` automatically increase the `optind` variable to point to the next command-line @@ -150,4 +150,4 @@ const char* file_name = argv[optind]; ## See also -* [`getopt`(5)](help://man/5/getopt) +- [`getopt`(5)](help://man/5/getopt) diff --git a/Base/usr/share/man/man3/isatty.md b/Base/usr/share/man/man3/isatty.md index f615d721b92..733e040e300 100644 --- a/Base/usr/share/man/man3/isatty.md +++ b/Base/usr/share/man/man3/isatty.md @@ -20,6 +20,6 @@ If `fd` refers to a TTY device, returns 1. Otherwise, returns 0 and `errno` is s ## Errors -* `EBADF`: `fd` is not an open file descriptor. -* `ENOTTY`: `fd` refers to something that's not a TTY device. -* `EINVAL`: `fd` refers to something that supports `ioctl()`, but is still not a TTY device. +- `EBADF`: `fd` is not an open file descriptor. +- `ENOTTY`: `fd` refers to something that's not a TTY device. +- `EINVAL`: `fd` refers to something that supports `ioctl()`, but is still not a TTY device. diff --git a/Base/usr/share/man/man3/posix_openpt.md b/Base/usr/share/man/man3/posix_openpt.md index 7734b7146e4..e6ab1c05908 100644 --- a/Base/usr/share/man/man3/posix_openpt.md +++ b/Base/usr/share/man/man3/posix_openpt.md @@ -1,6 +1,6 @@ ## Name -posix\_openpt - open a pseudo-terminal device +posix_openpt - open a pseudo-terminal device ## Synopsis @@ -13,13 +13,13 @@ int posix_openpt(int flags); ## Description -Open a pseudo-terminal master using the given *flags*. +Open a pseudo-terminal master using the given _flags_. -The *flags* argument accepts a bitmask of the following flags: +The _flags_ argument accepts a bitmask of the following flags: -* `O_RDWR`: Open for both reading and writing. -* `O_NOCTTY`: The opened pseudo-terminal will not be made the controlling TTY for the process. -* `O_CLOEXEC`: The opened fd shall be closed on [`exec`(2)](help://man/2/exec). +- `O_RDWR`: Open for both reading and writing. +- `O_NOCTTY`: The opened pseudo-terminal will not be made the controlling TTY for the process. +- `O_CLOEXEC`: The opened fd shall be closed on [`exec`(2)](help://man/2/exec). ## Return value @@ -31,4 +31,4 @@ Returns the same errors as [`open`(2)](help://man/2/open). ## See also -* [`open`(2)](help://man/2/open) +- [`open`(2)](help://man/2/open) diff --git a/Base/usr/share/man/man3/posix_spawn.md b/Base/usr/share/man/man3/posix_spawn.md index a0bafe7873a..f3c30563a3f 100644 --- a/Base/usr/share/man/man3/posix_spawn.md +++ b/Base/usr/share/man/man3/posix_spawn.md @@ -1,6 +1,6 @@ ## Name -posix\_spawn - launch a new process +posix_spawn - launch a new process ## Synopsis @@ -35,7 +35,7 @@ The new process is started as if the following steps are executed in this order: ## Return value If the process is successfully forked, returns 0. -Otherwise, returns an error number. This function does *not* return -1 on error and does *not* set `errno` like most other functions, it instead returns what other functions set `errno` to as result. +Otherwise, returns an error number. This function does _not_ return -1 on error and does _not_ set `errno` like most other functions, it instead returns what other functions set `errno` to as result. If the process forks successfully but spawnattr or file action processing or exec fail, `posix_spawn` returns 0 and the child exits with exit code `127`. @@ -62,5 +62,5 @@ int main() ## See also -* [`posix_spawnattr`(2)](help://man/3/posix_spawnattr_init) -* [`posix_spawn_file_actions`(2)](help://man/3/posix_spawn_file_actions_init) +- [`posix_spawnattr`(2)](help://man/3/posix_spawnattr_init) +- [`posix_spawn_file_actions`(2)](help://man/3/posix_spawn_file_actions_init) diff --git a/Base/usr/share/man/man3/posix_spawn_file_actions_init.md b/Base/usr/share/man/man3/posix_spawn_file_actions_init.md index 4f44ba4f9ce..5c8cc870344 100644 --- a/Base/usr/share/man/man3/posix_spawn_file_actions_init.md +++ b/Base/usr/share/man/man3/posix_spawn_file_actions_init.md @@ -47,4 +47,4 @@ If the effect of a file action fails, the child will exit with exit code 127 bef ## See also -* [`posix_spawn`(2)](help://man/3/posix_spawn) +- [`posix_spawn`(2)](help://man/3/posix_spawn) diff --git a/Base/usr/share/man/man3/posix_spawnattr_init.md b/Base/usr/share/man/man3/posix_spawnattr_init.md index 1ba01e3adb1..8f883b7972f 100644 --- a/Base/usr/share/man/man3/posix_spawnattr_init.md +++ b/Base/usr/share/man/man3/posix_spawnattr_init.md @@ -1,6 +1,6 @@ ## Name -posix\_spawnattr - configure attributes for posix\_spawn +posix_spawnattr - configure attributes for posix_spawn ## Synopsis @@ -48,23 +48,22 @@ It is valid to alternatingly call `posix_spawnattr_init()` and `posix_spawnattr_ `posix_spawnattr_setflags()` configures which attributes of the new child process `posix_spawn()` will set. It receives a bitmask that can contain: -* `POSIX_SPAWN_RESETIDS`: If set, `posix_spawn()` will reset the effective uid and gid of the child process to the real uid and gid of the parent process. See also [`setuid_overview`(7)](help://man/7/setuid_overview). +- `POSIX_SPAWN_RESETIDS`: If set, `posix_spawn()` will reset the effective uid and gid of the child process to the real uid and gid of the parent process. See also [`setuid_overview`(7)](help://man/7/setuid_overview). -* `POSIX_SPAWN_SETPGROUP`: If set, `posix_spawn()` will set the process group ID of the child process to the process group ID configured with `posix_spawnattr_setpgroup()`, as if `setpgid(0, pgroup)` was called in the child process. The behavior if both this and `POSIX_SPAWN_SETSID` is set is undefined. +- `POSIX_SPAWN_SETPGROUP`: If set, `posix_spawn()` will set the process group ID of the child process to the process group ID configured with `posix_spawnattr_setpgroup()`, as if `setpgid(0, pgroup)` was called in the child process. The behavior if both this and `POSIX_SPAWN_SETSID` is set is undefined. -* `POSIX_SPAWN_SETSCHEDPARAM`: If set, `posix_spawn()` will set the scheduler parameter of the child process to the process group ID configured with `posix_spawnattr_setschedparam()`, as if `sched_setparam(0, schedparam)` was called in the child process. +- `POSIX_SPAWN_SETSCHEDPARAM`: If set, `posix_spawn()` will set the scheduler parameter of the child process to the process group ID configured with `posix_spawnattr_setschedparam()`, as if `sched_setparam(0, schedparam)` was called in the child process. -* `POSIX_SPAWN_SETSCHEDULER`: This is not yet implemented in SerenityOS. +- `POSIX_SPAWN_SETSCHEDULER`: This is not yet implemented in SerenityOS. -* `POSIX_SPAWN_SETSIGDEF`: If set, `posix_spawn()` will reset the signal handlers of the child process configured with `posix_spawnattr_setsigdefault()` to each signal's default handler. +- `POSIX_SPAWN_SETSIGDEF`: If set, `posix_spawn()` will reset the signal handlers of the child process configured with `posix_spawnattr_setsigdefault()` to each signal's default handler. -* `POSIX_SPAWN_SETSIGMASK`: If set, `posix_spawn()` will set the signal mask of the child process to the signal mask configured with `posix_spawnattr_setsigmask()`, as if `sigprocmask()` was called in the child process. +- `POSIX_SPAWN_SETSIGMASK`: If set, `posix_spawn()` will set the signal mask of the child process to the signal mask configured with `posix_spawnattr_setsigmask()`, as if `sigprocmask()` was called in the child process. -* `POSIX_SPAWN_SETSID`: If set, `posix_spawn()` will run the child process in a new session, as if `setsid()` was called in the child process. The behavior if both this and `POSIX_SPAWN_SETPGROUP` is set is undefined. +- `POSIX_SPAWN_SETSID`: If set, `posix_spawn()` will run the child process in a new session, as if `setsid()` was called in the child process. The behavior if both this and `POSIX_SPAWN_SETPGROUP` is set is undefined. The `posix_spawnattr_get*` functions return what's been set with the corresponding setters. The default `flags` and `pgroup` are 0, the default `sigdefault` set is `sigemptyset()`, all other fields have an unspecified default value. - ## Return value In SerenityOS, these functions always succeed and return 0. @@ -75,4 +74,4 @@ If the effect of an attr fails, the child will exit with exit code 127 before ev ## See also -* [`posix_spawn`(2)](help://man/3/posix_spawn) +- [`posix_spawn`(2)](help://man/3/posix_spawn) diff --git a/Base/usr/share/man/man3/utimensat.md b/Base/usr/share/man/man3/utimensat.md index 560398dfdbb..1cc7df3ad5f 100644 --- a/Base/usr/share/man/man3/utimensat.md +++ b/Base/usr/share/man/man3/utimensat.md @@ -25,13 +25,13 @@ to the values specified in `times`. `utimensat()` functions in two ways. 1. Given a valid file descriptor for a directory and a non-empty path, -`utimensat()` updates the value of the file specified by the path relative to -the directory specified by the file descriptor. This is standard POSIX -behavior. + `utimensat()` updates the value of the file specified by the path relative to + the directory specified by the file descriptor. This is standard POSIX + behavior. 2. Given a valid file descriptor to a regular file and an empty path, -`utimensat()` updates the value of the file associated with the file -descriptor. This is not standard POSIX behavior, but it allows `futimens()` to -be implemented in terms of `utimensat()`. + `utimensat()` updates the value of the file associated with the file + descriptor. This is not standard POSIX behavior, but it allows `futimens()` to + be implemented in terms of `utimensat()`. If the `tv_nsec` field of `times` is set to UTIME_NOW, then the corresponding timestamp of the file is set to the current time. If the `tv_nsec` field of @@ -62,16 +62,16 @@ access and modification times of the specified file unmodified. `futimens()` and `utimensat()` may return the following error codes. -* `EFAULT`: `path` of `utimensat()` is a null pointer. -* `EINVAL`: Length of `path` is too long. -* `EINVAL`: `flag` is not 0 or `AT_SYMLINK_NOFOLLOW` -* `EINVAL`: The timestamp is not supported by the file system. -* `EINVAL`: Fields of `times` are less than 0 or greater than or equal to 1000 -million and not `UTIME_NOW` or `UTIME_OMIT`. -* `EACCES`: The current user does not have write access to the file. -* `EROFS`: The file system that contains the file is read-only. -* `ENOTDIR`: `path` is not absolute and `dirfd` is not a file descriptor -associated with a directory. +- `EFAULT`: `path` of `utimensat()` is a null pointer. +- `EINVAL`: Length of `path` is too long. +- `EINVAL`: `flag` is not 0 or `AT_SYMLINK_NOFOLLOW` +- `EINVAL`: The timestamp is not supported by the file system. +- `EINVAL`: Fields of `times` are less than 0 or greater than or equal to 1000 + million and not `UTIME_NOW` or `UTIME_OMIT`. +- `EACCES`: The current user does not have write access to the file. +- `EROFS`: The file system that contains the file is read-only. +- `ENOTDIR`: `path` is not absolute and `dirfd` is not a file descriptor + associated with a directory. ## Examples @@ -102,4 +102,4 @@ int main() ## See also -* [`touch`(1)](help://man/1/touch) +- [`touch`(1)](help://man/1/touch) diff --git a/Base/usr/share/man/man4/audio.md b/Base/usr/share/man/man4/audio.md index 38e8652239a..0b348d29fcd 100644 --- a/Base/usr/share/man/man4/audio.md +++ b/Base/usr/share/man/man4/audio.md @@ -6,10 +6,10 @@ audio - system audio devices `/dev/audio` is the directory for the system audio devices. Currently, there are only output devices, so every device file in the directory is an output channel. These channels are numbered, with `/dev/audio/0` being the first channel of the first device. To get the audio device to play audio, PCM samples need to be written to it as a series of "frames" (in MPEG terminology) or multi-channel samples with the following format: -| Byte | 0-1 | 2-3 | -|--|:--:|:--:| +| Byte | 0-1 | 2-3 | +| ------ | :-----------: | :-----------: | | Format | 16-bit signed | 16-bit signed | -| Data | Left sample | Right sample | +| Data | Left sample | Right sample | The sample rate of the samples is determined by the audio device's current sample rate, which may be accessed by an [ioctl](help://man/2/ioctl). @@ -17,9 +17,9 @@ Note that for convenience, the audio device may not block the call to `write` an ## Available `ioctl`s -* `SOUNDCARD_IOCTL_GET_SAMPLE_RATE`: Passes the current device sample rate (in samples per second) into a provided `u16*` (16-bit unsigned integer pointer). -* `SOUNDCARD_IOCTL_SET_SAMPLE_RATE`: Sets the sample rate of the underlying hardware from a provided 16-bit unsigned integer. Note that not all sound cards support all sample rate and the actually achieved sample rate should be checked with the GET_SAMPLE_RATE ioctl. +- `SOUNDCARD_IOCTL_GET_SAMPLE_RATE`: Passes the current device sample rate (in samples per second) into a provided `u16*` (16-bit unsigned integer pointer). +- `SOUNDCARD_IOCTL_SET_SAMPLE_RATE`: Sets the sample rate of the underlying hardware from a provided 16-bit unsigned integer. Note that not all sound cards support all sample rate and the actually achieved sample rate should be checked with the GET_SAMPLE_RATE ioctl. ## See also -* [Audio-subsystem](help://man/7/Audio-subsystem) +- [Audio-subsystem](help://man/7/Audio-subsystem) diff --git a/Base/usr/share/man/man4/full.md b/Base/usr/share/man/man4/full.md index fac94af4dbc..adb0a232f47 100644 --- a/Base/usr/share/man/man4/full.md +++ b/Base/usr/share/man/man4/full.md @@ -19,7 +19,7 @@ chmod 666 /dev/full ## Files -* /dev/full +- /dev/full ## Examples @@ -30,6 +30,5 @@ $ head -c 8 /dev/full | hexdump ## See also -* [`null`(4)](help://man/4/null) -* [`zero`(4)](help://man/4/zero) - +- [`null`(4)](help://man/4/null) +- [`zero`(4)](help://man/4/zero) diff --git a/Base/usr/share/man/man4/ipc.md b/Base/usr/share/man/man4/ipc.md index f98d013b22e..fead7e8bb74 100644 --- a/Base/usr/share/man/man4/ipc.md +++ b/Base/usr/share/man/man4/ipc.md @@ -13,11 +13,12 @@ The specifics of each service's format depend on the corresponding source `.ipc` The format can be identified by the format magic, which is derived in [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp`](../../../../../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp) from the service-endpoint name, e.g. "ClipboardClient" (which hashes to 4008793515) or "ClipboardServer" (which hashes to 1329211611). In general, communication works by packets, which might have been sent in response to other packets. Everything is host endianness. Each packet consists of: -- a 32-bit message size (see `Connection::try_parse_messages` in [`Userland/Libraries/LibIPC/Connection.h`](../../../../../Userland/Libraries/LibIPC/Connection.h)) -- the 32-bit endpoint magic (note that responses use the endpoint of the requesting packet, so the Clipboard server might use the endpoint magic 4008793515 to signal that this packet is a response) -- the 32-bit message ID within that endpoint (sequentially assigned, starting at 1) -- the data of that message itself (e.g. see `Messages::ClipboardServer::SetClipboardData::{en,de}code` in `Build/*/Userland/Services/Clipboard/ClipboardServerEndpoint.h`). + +- a 32-bit message size (see `Connection::try_parse_messages` in [`Userland/Libraries/LibIPC/Connection.h`](../../../../../Userland/Libraries/LibIPC/Connection.h)) +- the 32-bit endpoint magic (note that responses use the endpoint of the requesting packet, so the Clipboard server might use the endpoint magic 4008793515 to signal that this packet is a response) +- the 32-bit message ID within that endpoint (sequentially assigned, starting at 1) +- the data of that message itself (e.g. see `Messages::ClipboardServer::SetClipboardData::{en,de}code` in `Build/*/Userland/Services/Clipboard/ClipboardServerEndpoint.h`). ## See Also -- [ipc(5)](help://man/5/ipc) (IPC file format documentation) +- [ipc(5)](help://man/5/ipc) (IPC file format documentation) diff --git a/Base/usr/share/man/man4/mem.md b/Base/usr/share/man/man4/mem.md index 89288fe5fb6..e4d54c46fa1 100644 --- a/Base/usr/share/man/man4/mem.md +++ b/Base/usr/share/man/man4/mem.md @@ -16,6 +16,7 @@ are the reserved ranges in physical memory, essentially limiting the access to ROMs and memory-mapped PCI regions on x86. To create it manually: + ```sh mknod /dev/mem c 1 1 chmod 660 /dev/mem @@ -23,9 +24,9 @@ chmod 660 /dev/mem ## Returned error values after [`mmap`(2)](help://man/2/mmap) -* `EINVAL`: An access violation was detected. -* `ENOMEM`: The requested range would wrap around, creating an access violation. +- `EINVAL`: An access violation was detected. +- `ENOMEM`: The requested range would wrap around, creating an access violation. ## See also -* [`mmap`(2)](help://man/2/mmap) +- [`mmap`(2)](help://man/2/mmap) diff --git a/Base/usr/share/man/man4/null.md b/Base/usr/share/man/man4/null.md index 6263c358dee..2eec249fe0e 100644 --- a/Base/usr/share/man/man4/null.md +++ b/Base/usr/share/man/man4/null.md @@ -10,10 +10,9 @@ Reading from `/dev/null` returns end of file and exits with status 0. ## Files -* /dev/null +- /dev/null ## See also -* [`full`(4)](help://man/4/full) -* [`zero`(4)](help://man/4/zero) - +- [`full`(4)](help://man/4/full) +- [`zero`(4)](help://man/4/zero) diff --git a/Base/usr/share/man/man4/zero.md b/Base/usr/share/man/man4/zero.md index e1ea844cbc2..9c92dcde61b 100644 --- a/Base/usr/share/man/man4/zero.md +++ b/Base/usr/share/man/man4/zero.md @@ -10,7 +10,7 @@ Reading from `/dev/zero` returns '\0' bytes and exits with status 0. ## Files -* /dev/zero +- /dev/zero ## Examples @@ -21,6 +21,5 @@ $ head -c 8 /dev/zero | hexdump ## See also -* [`null`(4)](help://man/4/null) -* [`full`(4)](help://man/4/full) - +- [`null`(4)](help://man/4/null) +- [`full`(4)](help://man/4/full) diff --git a/Base/usr/share/man/man5/GML/CoreObject.md b/Base/usr/share/man/man5/GML/CoreObject.md index 53e4ada7313..96ccea642eb 100644 --- a/Base/usr/share/man/man5/GML/CoreObject.md +++ b/Base/usr/share/man/man5/GML/CoreObject.md @@ -8,7 +8,7 @@ All GML widgets inherit properties from `Core::Object`. ## Registered Properties -| Property | Type | Possible values | Description | -|-------------|-----------------|-----------------|------------------------------------------------| -| name | string | Any string | Name of widget, to be referenced later in C++. | -| class_name | readonly_string | Class name | Object class | +| Property | Type | Possible values | Description | +| ---------- | --------------- | --------------- | ---------------------------------------------- | +| name | string | Any string | Name of widget, to be referenced later in C++. | +| class_name | readonly_string | Class name | Object class | diff --git a/Base/usr/share/man/man5/GML/UI-Dimensions.md b/Base/usr/share/man/man5/GML/UI-Dimensions.md index b89921f55e3..a7183e477ff 100644 --- a/Base/usr/share/man/man5/GML/UI-Dimensions.md +++ b/Base/usr/share/man/man5/GML/UI-Dimensions.md @@ -19,11 +19,10 @@ Special Values carry size information that would otherwise not be intuitively po Importantly, while any "regular" (i.e. int ≥0) UI Dimension values might (by convention) be assigned to any UI Dimension property, many properties only allow a subset of the "special" values to be assigned to them. -| Name | c++ name | GML/JSON representation | General meaning | -|-------------------|--------------------------------------------|-------------------------|-------------------------------------------------| -| Regular | `GUI::SpecialDimension::Regular` (mock) | int ≥0 | This is a regular integer value specifying a specific size | -| Grow | `GUI::SpecialDimension::Grow` | `"grow"` | Grow to the maximum size the surrounding allows | +| Name | c++ name | GML/JSON representation | General meaning | +| ----------------- | ------------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Regular | `GUI::SpecialDimension::Regular` (mock) | int ≥0 | This is a regular integer value specifying a specific size | +| Grow | `GUI::SpecialDimension::Grow` | `"grow"` | Grow to the maximum size the surrounding allows | | OpportunisticGrow | `GUI::SpecialDimension::OpportunisticGrow` | `"opportunistic_grow"` | Grow when the opportunity arises, meaning — only when all other widgets have already grown to their maximum size, and only opportunistically growing widgets are left | -| Fit | `GUI::SpecialDimension::Fit` | `"fit"` | Grow exactly to the size of the surrounding as determined by other factors, but do not call for e.g. expansion of the parent container itself | -| Shrink | `GUI::SpecialDimension::Shrink` | `"shrink"` | Shrink to the smallest size possible | - +| Fit | `GUI::SpecialDimension::Fit` | `"fit"` | Grow exactly to the size of the surrounding as determined by other factors, but do not call for e.g. expansion of the parent container itself | +| Shrink | `GUI::SpecialDimension::Shrink` | `"shrink"` | Shrink to the smallest size possible | diff --git a/Base/usr/share/man/man5/GML/Widget.md b/Base/usr/share/man/man5/GML/Widget.md index da3c2ae208c..99bcc7df323 100644 --- a/Base/usr/share/man/man5/GML/Widget.md +++ b/Base/usr/share/man/man5/GML/Widget.md @@ -51,4 +51,3 @@ Defines a GUI widget. | fill_width_background_color | bool | | Whether to fill the widget's background with the background color | | layout | layout object | | Layout object for layouting this widget's children | | relative_rect | rect | | Rectangle for relatively positioning the widget to the parent | - diff --git a/Base/usr/share/man/man5/GML/Widget/CheckBox.md b/Base/usr/share/man/man5/GML/Widget/CheckBox.md index abe4b201f25..6c6861a8654 100644 --- a/Base/usr/share/man/man5/GML/Widget/CheckBox.md +++ b/Base/usr/share/man/man5/GML/Widget/CheckBox.md @@ -28,9 +28,10 @@ Defines a GUI checkbox widget. ## Registered Properties | Property | Type | Possible values | Description | -|-------------------|--------|-------------------|--------------------------------------------------------------------| +| ----------------- | ------ | ----------------- | ------------------------------------------------------------------ | | autosize | bool | true or false | Determines if auto-sized | | checkbox_position | String | "Left" or "Right" | Place the checkbox itself on either the left or right of its label | ## See also -- [GML Button](help://man/5/GML/Widget/Button) + +- [GML Button](help://man/5/GML/Widget/Button) diff --git a/Base/usr/share/man/man5/GML/Widget/ColorInput.md b/Base/usr/share/man/man5/GML/Widget/ColorInput.md index 4bed8ca95dc..3b54b3c8b70 100644 --- a/Base/usr/share/man/man5/GML/Widget/ColorInput.md +++ b/Base/usr/share/man/man5/GML/Widget/ColorInput.md @@ -27,6 +27,6 @@ Defines a GUI color input widget. ## Registered Properties | Property | Type | Possible values | Description | -|--------------------|--------|-----------------|---------------------------------------------------------| +| ------------------ | ------ | --------------- | ------------------------------------------------------- | | color_picker_title | string | Any string | Sets the title of the input | | has_alpha_channel | bool | true or false | Whether to include the alpha channel in color selection | diff --git a/Base/usr/share/man/man5/GML/Widget/ComboBox.md b/Base/usr/share/man/man5/GML/Widget/ComboBox.md index 513cdd8dd8c..842d5089cad 100644 --- a/Base/usr/share/man/man5/GML/Widget/ComboBox.md +++ b/Base/usr/share/man/man5/GML/Widget/ComboBox.md @@ -27,6 +27,6 @@ Defines a GUI combo box widget. Another name for this would be a dropdown or sel ## Registered Properties | Property | Type | Possible values | Description | -|-------------|--------|-----------------|------------------------------| +| ----------- | ------ | --------------- | ---------------------------- | | placeholder | string | Any string | Editor placeholder | | model_only | bool | true or false | Only allow values from model | diff --git a/Base/usr/share/man/man5/GML/Widget/DynamicWidgetContainer.md b/Base/usr/share/man/man5/GML/Widget/DynamicWidgetContainer.md index 43d11f15da1..84b4bec562d 100644 --- a/Base/usr/share/man/man5/GML/Widget/DynamicWidgetContainer.md +++ b/Base/usr/share/man/man5/GML/Widget/DynamicWidgetContainer.md @@ -6,13 +6,13 @@ GML DynamicWidgetContainer Defines a container widget that will group its child widgets together so that they can be collapsed, expanded or detached to a new window as one unit. If DynamicWidgetContainers are nested within one DynamicWidgetContainer it is possible to move the positions of the child containers dynamically. -| Property | Description | -| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| config_domain | Defines if the changes to the widget's view state should be persisted. It is required that the domain has been already pleged by the application. | -| detached_size | Defines a size that the detached widget window should initially have. If not defined, the window will have the current size of the widget. | -| section_label | The label that will be used for the section. | -| show_controls | Defines if the buttons and label should be visible or not. This allows e.g. a parent container to hide its controls but provide rearrenage functionality. | -| with_individual_order | Configured on a parent container to enable the persistence of rearranged child containers. | +| Property | Description | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| config_domain | Defines if the changes to the widget's view state should be persisted. It is required that the domain has been already pleged by the application. | +| detached_size | Defines a size that the detached widget window should initially have. If not defined, the window will have the current size of the widget. | +| section_label | The label that will be used for the section. | +| show_controls | Defines if the buttons and label should be visible or not. This allows e.g. a parent container to hide its controls but provide rearrenage functionality. | +| with_individual_order | Configured on a parent container to enable the persistence of rearranged child containers. | ## Synopsis @@ -21,13 +21,14 @@ Defines a container widget that will group its child widgets together so that th ## Examples Simple container: + ```gml @GUI::DynamicWidgetContainer { section_label: "Section 1" @GUI::Widget { } - + @GUI::Widget { } } @@ -48,20 +49,20 @@ Nested containers with persistence: @GUI::Widget { } - + @GUI::Widget { } } - + @GUI::DynamicWidgetContainer { section_label: "Section 2" config_domain: "abc" @GUI::Widget { } - + @GUI::Widget { } - } + } } ``` diff --git a/Base/usr/share/man/man5/GML/Widget/Frame.md b/Base/usr/share/man/man5/GML/Widget/Frame.md index da66e93a271..0446b5c6859 100644 --- a/Base/usr/share/man/man5/GML/Widget/Frame.md +++ b/Base/usr/share/man/man5/GML/Widget/Frame.md @@ -26,7 +26,7 @@ Defines a GUI frame widget. Frames can contain other GUI widgets. ## Registered Properties | Property | Type | Possible values | Description | -|-----------|---------|--------------------------------------------------------------|--------------------| +| --------- | ------- | ------------------------------------------------------------ | ------------------ | | thickness | integer | 64-bit integer | Sets the thickness | | shadow | enum | Plain, Raised, Sunken | Sets the shadow | | shape | enum | NoFrame, Box, Container, Panel, VerticalLine, HorizontalLine | Sets the shape | diff --git a/Base/usr/share/man/man5/GML/Widget/GroupBox.md b/Base/usr/share/man/man5/GML/Widget/GroupBox.md index b1db09260c3..fa0af4865b4 100644 --- a/Base/usr/share/man/man5/GML/Widget/GroupBox.md +++ b/Base/usr/share/man/man5/GML/Widget/GroupBox.md @@ -21,5 +21,5 @@ Defines a GUI group box widget. Used to contain widgets in a border with a title ## Registered Properties | Property | Type | Possible values | Description | -|----------|--------|-----------------|----------------| +| -------- | ------ | --------------- | -------------- | | title | string | Any string | Sets the title | diff --git a/Base/usr/share/man/man5/GML/Widget/ImageWidget.md b/Base/usr/share/man/man5/GML/Widget/ImageWidget.md index 6dd79731613..2a814022ab8 100644 --- a/Base/usr/share/man/man5/GML/Widget/ImageWidget.md +++ b/Base/usr/share/man/man5/GML/Widget/ImageWidget.md @@ -21,6 +21,6 @@ Defines a GUI image widget. ## Registered Properties | Property | Type | Possible values | Description | -|----------------|------|-----------------|-------------------------------------| +| -------------- | ---- | --------------- | ----------------------------------- | | auto_resize | bool | true or false | Set if the image should auto-resize | | should_stretch | bool | true or false | Set if the image should stretch | diff --git a/Base/usr/share/man/man5/GML/Widget/Label.md b/Base/usr/share/man/man5/GML/Widget/Label.md index f53b5273c34..f4ce09dcfc9 100644 --- a/Base/usr/share/man/man5/GML/Widget/Label.md +++ b/Base/usr/share/man/man5/GML/Widget/Label.md @@ -24,7 +24,7 @@ Defines a GUI label widget. ## Registered Properties -| Property | Type | Possible values | Description | -|-----------------|----------------|-----------------------------------------------------------------------------|----------------------------| -| text_alignment | text_alignment | Center, CenterLeft, CenterRight, TopLeft, TopRight, BottomLeft, BottomRight | Sets alignment of the text | -| text_wrapping | text_wrapping | | | | | +| Property | Type | Possible values | Description | +| -------------- | -------------- | --------------------------------------------------------------------------- | -------------------------- | --- | --- | +| text_alignment | text_alignment | Center, CenterLeft, CenterRight, TopLeft, TopRight, BottomLeft, BottomRight | Sets alignment of the text | +| text_wrapping | text_wrapping | | | | | diff --git a/Base/usr/share/man/man5/GML/Widget/NumericInput.md b/Base/usr/share/man/man5/GML/Widget/NumericInput.md index 89b1b23e4f3..83f84d8d600 100644 --- a/Base/usr/share/man/man5/GML/Widget/NumericInput.md +++ b/Base/usr/share/man/man5/GML/Widget/NumericInput.md @@ -22,8 +22,8 @@ Defines a GUI text box that only allows integers within a specified range. ## Registered Properties -| Property | Type | Possible values | Description | -|----------|-------|--------------------|----------------------------------------| -| min | int | Any 64 bit integer | Minimum number the input can be set to | -| max | int | Any 64 bit integer | Maximum number the input can be set to | -| value | int | Any 64 bit integer | Initial value | +| Property | Type | Possible values | Description | +| -------- | ---- | ------------------ | -------------------------------------- | +| min | int | Any 64 bit integer | Minimum number the input can be set to | +| max | int | Any 64 bit integer | Maximum number the input can be set to | +| value | int | Any 64 bit integer | Initial value | diff --git a/Base/usr/share/man/man5/GML/Widget/Progressbar.md b/Base/usr/share/man/man5/GML/Widget/Progressbar.md index 5f10831ee31..f977df961aa 100644 --- a/Base/usr/share/man/man5/GML/Widget/Progressbar.md +++ b/Base/usr/share/man/man5/GML/Widget/Progressbar.md @@ -25,7 +25,7 @@ Defines a GUI progress bar widget. ## Registered Properties | Property | Type | Possible values | Description | -|----------|--------|-----------------------------------|--------------------------------------------| +| -------- | ------ | --------------------------------- | ------------------------------------------ | | text | string | Any string | Sets progress text | | format | enum | NoText, Percentage, ValueSlashMax | Sets the format of the progress indication | | min | int | Any 64 bit integer | Sets the minimum progress value | diff --git a/Base/usr/share/man/man5/GML/Widget/ScrollableContainerWidget.md b/Base/usr/share/man/man5/GML/Widget/ScrollableContainerWidget.md index 38bcd53c7b9..6db577ea1c1 100644 --- a/Base/usr/share/man/man5/GML/Widget/ScrollableContainerWidget.md +++ b/Base/usr/share/man/man5/GML/Widget/ScrollableContainerWidget.md @@ -27,7 +27,7 @@ Content declared as `content_widget` property. ## Registered Properties | Property | Type | Possible values | Description | -|------------------------------------|---------------|------------------------|---------------------------------------------| +| ---------------------------------- | ------------- | ---------------------- | ------------------------------------------- | | ~~layout~~ | | none | Does not take layout | | scrollbars_enabled | bool | true or false | Status of scrollbar | | should_hide_unnecessary_scrollbars | bool | true or false | Whether to hide scrollbars when unnecessary | diff --git a/Base/usr/share/man/man5/GML/Widget/Slider.md b/Base/usr/share/man/man5/GML/Widget/Slider.md index d69183bc218..55e2a067d00 100644 --- a/Base/usr/share/man/man5/GML/Widget/Slider.md +++ b/Base/usr/share/man/man5/GML/Widget/Slider.md @@ -21,5 +21,5 @@ Defines a GUI slider widget. ## Registered Properties | Property | Type | Possible values | Description | -|----------------|------|---------------------|---------------------------| +| -------------- | ---- | ------------------- | ------------------------- | | knob_size_mode | enum | Fixed, Proportional | Sets the slider knob size | diff --git a/Base/usr/share/man/man5/GML/Widget/SpinBox.md b/Base/usr/share/man/man5/GML/Widget/SpinBox.md index 7612510c6d0..06e23cbeba7 100644 --- a/Base/usr/share/man/man5/GML/Widget/SpinBox.md +++ b/Base/usr/share/man/man5/GML/Widget/SpinBox.md @@ -22,7 +22,7 @@ Defines a GUI spin box widget. This is a number input with buttons to increment ## Registered Properties -| Property | Type | Possible values | Description | -|----------|-------|--------------------|----------------------------------------------| -| min | int | Any 64 bit integer | Minimum number the spin box can increment to | -| max | int | Any 64 bit integer | Maximum number the spin box can increment to | +| Property | Type | Possible values | Description | +| -------- | ---- | ------------------ | -------------------------------------------- | +| min | int | Any 64 bit integer | Minimum number the spin box can increment to | +| max | int | Any 64 bit integer | Maximum number the spin box can increment to | diff --git a/Base/usr/share/man/man5/GML/Widget/Statusbar.md b/Base/usr/share/man/man5/GML/Widget/Statusbar.md index 0dd3989b414..6a191e32561 100644 --- a/Base/usr/share/man/man5/GML/Widget/Statusbar.md +++ b/Base/usr/share/man/man5/GML/Widget/Statusbar.md @@ -21,6 +21,6 @@ Defines a GUI status bar widget. ## Registered Properties | Property | Type | Possible values | Description | -|-------------|--------|--------------------|---------------------------------| +| ----------- | ------ | ------------------ | ------------------------------- | | text | string | Any string | Sets the text of the status bar | | label_count | int | Any 64 bit integer | Sets the label count | diff --git a/Base/usr/share/man/man5/GML/Widget/TabWidget.md b/Base/usr/share/man/man5/GML/Widget/TabWidget.md index 2c8cb548a4c..69c82bfd504 100644 --- a/Base/usr/share/man/man5/GML/Widget/TabWidget.md +++ b/Base/usr/share/man/man5/GML/Widget/TabWidget.md @@ -15,7 +15,7 @@ Defines a GUI tab widget. ```gml @GUI::TabWidget { uniform_tabs: true - + @GUI::Widget { title: "First tab" } @@ -28,7 +28,7 @@ Defines a GUI tab widget. ## Registered Properties | Property | Type | Possible values | Description | -|--------------------|----------------|-----------------------------------------------------------------------------|--------------------------------------| +| ------------------ | -------------- | --------------------------------------------------------------------------- | ------------------------------------ | | container_margins | margins | | Margins for the tab content | | reorder_allowed | bool | true or false | Allow changing the order of the tabs | | show_close_buttons | bool | true or false | Show a close button on each tab | diff --git a/Base/usr/share/man/man5/GML/Widget/TextEditor.md b/Base/usr/share/man/man5/GML/Widget/TextEditor.md index 6bc5174e3ad..087b5f6dd2b 100644 --- a/Base/usr/share/man/man5/GML/Widget/TextEditor.md +++ b/Base/usr/share/man/man5/GML/Widget/TextEditor.md @@ -22,7 +22,7 @@ Defines a GUI text editor widget. ## Registered Properties | Property | Type | Possible values | Description | -|-------------|--------|---------------------------------|-----------------| +| ----------- | ------ | ------------------------------- | --------------- | | text | string | Any string | Set text | | placeholder | string | Any string | Set placeholder | | mode | enum | Editable, ReadOnly, DisplayOnly | Set editor mode | diff --git a/Base/usr/share/man/man5/GML/Widget/Toolbar.md b/Base/usr/share/man/man5/GML/Widget/Toolbar.md index 0490271c6da..8e6b5eca42c 100644 --- a/Base/usr/share/man/man5/GML/Widget/Toolbar.md +++ b/Base/usr/share/man/man5/GML/Widget/Toolbar.md @@ -27,6 +27,6 @@ To keep groups (i.e. Buttons/items separated by Separators) together, and move t ## Registered Properties | Property | Type | Possible values | Description | -|-------------|------|-----------------|---------------------------------------------------------------------------------------| +| ----------- | ---- | --------------- | ------------------------------------------------------------------------------------- | | collapsible | bool | true or false | If items that do not fit should be placed in an overflow menu | | grouped | bool | true or false | If items should be moved to the overflow menu in groups, separated by Separator items | diff --git a/Base/usr/share/man/man5/Network.md b/Base/usr/share/man/man5/Network.md index a8106ed9331..36809990e70 100644 --- a/Base/usr/share/man/man5/Network.md +++ b/Base/usr/share/man/man5/Network.md @@ -16,11 +16,11 @@ The interface that is not listed in this config file has DHCP enabled by default ## Options -* `Enabled` (default: `true`) - Whether the interface is enabled. -* `DHCP` (default: `false`) - Whether the DHCP client should be run on this interface. This overrides static IP settings. -* `IPv4Address` (default: `0.0.0.0`) - The static IPv4 address for the interface. Used only when `DHCP` is `false`. -* `IPv4Netmask` (default: `0.0.0.0`) - The static IPv4 netmask for the interface. Used only when `DHCP` is `false`. -* `IPv4Gateway` (default: `0.0.0.0`) - The static IPv4 default gateway for the interface. Used only when `DHCP` is `false`. +- `Enabled` (default: `true`) - Whether the interface is enabled. +- `DHCP` (default: `false`) - Whether the DHCP client should be run on this interface. This overrides static IP settings. +- `IPv4Address` (default: `0.0.0.0`) - The static IPv4 address for the interface. Used only when `DHCP` is `false`. +- `IPv4Netmask` (default: `0.0.0.0`) - The static IPv4 netmask for the interface. Used only when `DHCP` is `false`. +- `IPv4Gateway` (default: `0.0.0.0`) - The static IPv4 default gateway for the interface. Used only when `DHCP` is `false`. ## Example @@ -41,4 +41,5 @@ Enabled=false ``` ## See Also -* [`ifconfig`(1)](help://man/1/ifconfig) + +- [`ifconfig`(1)](help://man/1/ifconfig) diff --git a/Base/usr/share/man/man5/Shell.md b/Base/usr/share/man/man5/Shell.md index f3348212497..b50187de820 100644 --- a/Base/usr/share/man/man5/Shell.md +++ b/Base/usr/share/man/man5/Shell.md @@ -6,15 +6,15 @@ The Shell Command Language The shell operates according to the following general steps: -* Some string is read from a source, be it a file, the standard input, or a command string (see [`Shell`(1)](help://man/1/Shell)) -* The shell parses the input to an abstract syntax tree -* The shell performs various expansions and/or resolutions on the nodes -* The shell performs various type checks and syntactic checks -* The shell interprets the AST, evaluating commands as needed -* For each given command, the shell flattens all the string/list arguments -* For each given command, the shell records the applicable redirections -* Should a command be executed, the shell applies the redirections, and executes the command with the flattened argument list -* Should a command need waiting, the shell shall wait for the command to finish, and continue execution +- Some string is read from a source, be it a file, the standard input, or a command string (see [`Shell`(1)](help://man/1/Shell)) +- The shell parses the input to an abstract syntax tree +- The shell performs various expansions and/or resolutions on the nodes +- The shell performs various type checks and syntactic checks +- The shell interprets the AST, evaluating commands as needed +- For each given command, the shell flattens all the string/list arguments +- For each given command, the shell records the applicable redirections +- Should a command be executed, the shell applies the redirections, and executes the command with the flattened argument list +- Should a command need waiting, the shell shall wait for the command to finish, and continue execution Any text below is superseded by the formal grammar defined in the _formal grammar_ section. @@ -23,109 +23,131 @@ Any text below is superseded by the formal grammar defined in the _formal gramma This section describes the general tokens the language accepts, it should be noted that due to nature of the language, some tokens are valid only in a specific context. ##### Bareword + String of characters that are not _Special_ or _Syntactic Elements_ ##### Glob + String of characters containing at least one of `*?` in _bareword_ position ##### History Events + A _designator_ starting with `!` in _bareword_ position that describes a word or a range of words from a previously entered command. Please look at the section named 'History Event Designators' for a more thorough explanation. Only allowed in interactive mode. ##### Single Quoted String + Any sequence of characters between two single quotes (`'`) ##### Double Quoted String + Any sequence of _Double Quoted String Part_ tokens: -* Barewords -* Single Quotes -* Variable References -* History Events -* Evaluate expressions -* Escaped sequences + +- Barewords +- Single Quotes +- Variable References +- History Events +- Evaluate expressions +- Escaped sequences ##### Heredocs + Heredocs are made in two parts, the _initiator_ and the _contents_, the _initiator_ may be used in place of a string (i.e. wherever a string is allowed to be used), with the constraint that the _contents_ must follow the _sequence_ that the _initiator_ is used in. There are four different _initiators_: -- `<<-token`: The _contents_ may contain interpolations, and are terminated with a line containing only whitespace and then _token_ -- `<<-'token'`: The _contents_ may _not_ contain interpolations, but otherwise is the same as `<<-token` -- `<<~token`: Similar to `<<-token`, but the starting whitespace of the lines in the _contents_ is stripped, note that this happens after any and all expansions/interpolations are done. -- `<<~'token'`: Dedents (i.e. strips the initial whitespace) like `<<~token`, and disallows interpolations like `<<-'token'`. + +- `<<-token`: The _contents_ may contain interpolations, and are terminated with a line containing only whitespace and then _token_ +- `<<-'token'`: The _contents_ may _not_ contain interpolations, but otherwise is the same as `<<-token` +- `<<~token`: Similar to `<<-token`, but the starting whitespace of the lines in the _contents_ is stripped, note that this happens after any and all expansions/interpolations are done. +- `<<~'token'`: Dedents (i.e. strips the initial whitespace) like `<<~token`, and disallows interpolations like `<<-'token'`. Note that heredocs _must_ be listed in the same order as they are used after a sequence that has been terminated with a newline. ##### Variable Reference + Any sequence of _Identifier_ characters, or a _Special Variable_ following a `$`. Variables may be followed by a _Slice_ (see [Slice](#slice)) ##### Slice + Variables may be sliced into, which will allow the user to select a subset of entries in the contents of the variable. An expression of the form $_identifier_[_slice-contents_] can be used to slice into a variable, where _slice-contents_ has semantics similar to _Brace Expansions_, but it may only evaluate to numeric values, that are used to index into the variable being sliced. Negative indices are allowed, and will index the contents from the end. It should be noted that the shell will always perform bounds-checking on the indices, and raise an error on out-of-bound accesses. Slices can slice into both lists and strings. For example, `$lst[1..-2]` can be used to select a permutation of a 4-element list referred to by the variable `lst`, as the slice will evaluate to the list `(1 0 -1 -2)`, which will select the indices 1, 0, 3, 2 (in that order). - ##### Immediate Expressions + An expression of the form '${identifier expression...}', such expressions are expanded to other kinds of nodes before resolution, and are internal functions provided by the shell. Currently, the following functions are exposed: -- ${length (string|list)? _expression_} -Finds the length of the given _expression_. if either `string` or `list` is given, the shell will attempt to treat _expression_ as that type, otherwise the type of _expression_ will be inferred. -- ${length\_across (string|list) _expression_} -Finds the lengths of the entries in _expression_, this requires _expression_ to be a list. -If either `string` or `list` is given, the shell attempts to treat the elements of _expression_ as that type, otherwise the types are individually inferred. +- ${length (string|list)? _expression_} + Finds the length of the given _expression_. if either `string` or `list` is given, the shell will attempt to treat _expression_ as that type, otherwise the type of _expression_ will be inferred. -- ${split _delimiter_ _string_} -Splits the _string_ with _delimiter_, and evaluates to a list. -Both _string_ and _delimiter_ must be strings. +- ${length*across (string|list) \_expression*} + Finds the lengths of the entries in _expression_, this requires _expression_ to be a list. + If either `string` or `list` is given, the shell attempts to treat the elements of _expression_ as that type, otherwise the types are individually inferred. -- ${remove\_suffix _suffix_ _string_} -Removes the suffix _suffix_ (if present) from the given _string_. +- ${split _delimiter_ _string_} + Splits the _string_ with _delimiter_, and evaluates to a list. + Both _string_ and _delimiter_ must be strings. -- ${remove\_prefix _prefix_ _string_} -Removes the prefix _prefix_ (if present) from the given _string_. +- ${remove*suffix \_suffix* _string_} + Removes the suffix _suffix_ (if present) from the given _string_. -- ${concat\_lists _list_...} -Concatenates all the given expressions as lists, and evaluates to a list. +- ${remove*prefix \_prefix* _string_} + Removes the prefix _prefix_ (if present) from the given _string_. -- ${regex\_replace _pattern_ _replacement-template_ _string_} -Replaces all occurrences of the regular expression _pattern_ in the given _string_, using the given _replacement-template_. -Capture groups in _pattern_ can be referred to as `\<group_number>` in the _replacement template_, for example, to reference capture group 1, use `\1`. +- ${concat*lists \_list*...} + Concatenates all the given expressions as lists, and evaluates to a list. + +- ${regex*replace \_pattern* _replacement-template_ _string_} + Replaces all occurrences of the regular expression _pattern_ in the given _string_, using the given _replacement-template_. + Capture groups in _pattern_ can be referred to as `\<group_number>` in the _replacement template_, for example, to reference capture group 1, use `\1`. ##### Evaluate expression + Any expression following a `$` that is not a variable reference: -* Inline execution: A _syntactic list_ following a `$`: -* Dynamic evaluation: Any other expression following a `$` + +- Inline execution: A _syntactic list_ following a `$`: +- Dynamic evaluation: Any other expression following a `$` ##### Lists + Any two expressions joined by the Join operator (` ` [whitespace]), or a _variable reference_ referring to a list value -* Syntactic Lists: Any _list_ enclosed in parentheses (`(` and `)`) + +- Syntactic Lists: Any _list_ enclosed in parentheses (`(` and `)`) ##### Comments + Any text following and including that in a word starting with `#`, up to but not including a newline ##### Keywords + The following tokens: -* `for` in command name position -* `in` as a syntactic element of a `for` expression -* `if` in command name position, or after the `else` keyword -* `else` after a partial `if` expression -* `match` in command name position -* `as` as part of a `match` expression + +- `for` in command name position +- `in` as a syntactic element of a `for` expression +- `if` in command name position, or after the `else` keyword +- `else` after a partial `if` expression +- `match` in command name position +- `as` as part of a `match` expression ##### Special characters + Any of the following: -* `;` in bareword position -* `\\n` (a newline) in _bareword_ position -* Any of `(){}` -* Any of `*?` not in _glob_ position + +- `;` in bareword position +- `\\n` (a newline) in _bareword_ position +- Any of `(){}` +- Any of `*?` not in _glob_ position ##### Tilde + Any initial path segment starting with the character `~` in _bareword_ position, Optionally followed by a _bareword_ for the username ## Redirections + The shell can create various redirections to file descriptors of a command before executing it, the general syntax for redirections is an optional file descriptor, followed by a redirection operator, followed by a destination. There are four redirection operators corresponding to various file descriptor open modes: `Read`, `Write`, `WriteAppend` and `ReadWrite`, respectively `<`, `>`, `>>` and `<>`. @@ -133,15 +155,19 @@ There are four redirection operators corresponding to various file descriptor op A special syntactic element `&fd` can reference a file descriptor as a destination. Redirections take two main forms, Read/Write redirections, and fd closure redirections. + ##### Read/Write -* Allowed operators: all -* Allowed destinations: file paths (any shell _expression_) and _file descriptor references_ + +- Allowed operators: all +- Allowed destinations: file paths (any shell _expression_) and _file descriptor references_ ##### Close -* Allowed operators: `Write` (`>`) -* Allowed destinations: the special "close" reference `&-` + +- Allowed operators: `Write` (`>`) +- Allowed destinations: the special "close" reference `&-` #### Examples + ```sh # Redirect the standard error to a file, and close the standard input $ 2> foo 1>&- @@ -154,36 +180,43 @@ $ >/dev/null ``` ## Expansions + The shell performs various expansions, in different stages. -* Glob Expansion: Globs shall be expanded to a list. +- Glob Expansion: Globs shall be expanded to a list. -* Variable Expansion: Variables shall be expanded preserving their types. +- Variable Expansion: Variables shall be expanded preserving their types. -* Brace Expansions: Brace expansions shall be expanded to a list. +- Brace Expansions: Brace expansions shall be expanded to a list. -* Juxtaposition Expansion: Juxtapositions shall be expanded as list products. +- Juxtaposition Expansion: Juxtapositions shall be expanded as list products. -* Other expansions: Tildes, Evaluate expressions, etc. shall be expanded as needed. +- Other expansions: Tildes, Evaluate expressions, etc. shall be expanded as needed. ### Brace Expansions + Brace expansions are of two kinds, _normal brace expansions_ and _range brace expansions_. _Normal brace expansions_ are sequences of optional expressions inside braces (`{}`), delimited by a comma (`','`); a missing expression is treated as an empty string literal. Such expressions are simply expanded to the expressions they enclose. _Range brace expansions_ are of the form `{start_expression..end_expression}`, where `start_expression` and `end_expression` denote the bounds of an inclusive _range_, and can be one of two types: -- Single unicode code points: The range expands to all code points between the start and end, e.g. `{a..c}` shall expand to the list `(a b c)`. -- Numbers: The range expands to all numbers between the start and end, e.g. `{8..11}` shall expand to the list `(8 9 10 11)`. + +- Single unicode code points: The range expands to all code points between the start and end, e.g. `{a..c}` shall expand to the list `(a b c)`. +- Numbers: The range expands to all numbers between the start and end, e.g. `{8..11}` shall expand to the list `(8 9 10 11)`. ### Juxtapositions + Any two expressions joined without any operator are considered to be in a Juxtaposition, with the resulting value being the list product of two expressions. For instance, `(1 2)(3 4)` shall be evaluated to `(13 14 23 24)` by calculating the list product of the two expressions `(1 2)` and `(3 4)`. ### Tildes + Any bareword starting with a tilde (`~`) and spanning up to the first path separator (`/`) - or EOL - is considered to be a tilde expansion with the text between the tilde and the separator being the _username_, which shall be expanded to a single string containing the home directory of the given _username_ (or the current user if no username is provided). ### Evaluate + Evaluate expressions take the general form of a dollar sign (`$`) followed by some _expression_, which is evaluated by the rules below. -- Should the _expression_ be a string, it shall be evaluated as a dynamic variable lookup by first evaluating the string, and then looking up the given variable. -- Should the _expression_ be a list or a command, it shall be converted to a command, whose output (from the standard output) shall be captured, and split to a list with the shell local variable `IFS` (or the default splitter `\n` (newline, 0x0a)). It should be noted that the shell option `inline_exec_keep_empty_segments` will determine whether empty segments in the split list shall be preserved when this expression is evaluated, this behavior is disabled by default. + +- Should the _expression_ be a string, it shall be evaluated as a dynamic variable lookup by first evaluating the string, and then looking up the given variable. +- Should the _expression_ be a list or a command, it shall be converted to a command, whose output (from the standard output) shall be captured, and split to a list with the shell local variable `IFS` (or the default splitter `\n` (newline, 0x0a)). It should be noted that the shell option `inline_exec_keep_empty_segments` will determine whether empty segments in the split list shall be preserved when this expression is evaluated, this behavior is disabled by default. ## Commands @@ -192,31 +225,38 @@ A `Command` is a single simple command, containing arguments and redirections fo Commands can be either calls to Shell builtins, or external programs. ## Shell Semantic Elements + The commands can be composed into semantic elements, producing composite commands: ### Sequences + A sequence of commands, executed serially independent of each other: `Command ; Command ; Command ...` It should be noted that a newline (`\\n`) can be substituted for the semicolon (`;`). #### Example + ```sh # Do one thing, then do another echo foo; echo bar ``` ### Logical Relations + A sequence of commands whose execution depends somehow on the result of another #### `Command && Command && Command ...` (AND) + Short-circuiting command evaluations, will cancel the entire chain should any command fails (have a non-zero exit code) #### `Command || Command || Command ...` (OR) + Short-circuiting command evaluation, will continue down the chain if any command fails. It should be noted that `And` chains bind more tightly than `Or` chains, so an expression of the form `C1 && C2 || C3` is understood as "evaluate `C1`, if successful, evaluate `C2`, if not successful, evaluate `C3`". ##### Examples + ```sh # Create file if not found test -f foo.txt || touch foo.txt @@ -228,6 +268,7 @@ rm test && echo "deleted!" || echo "failed with $?" #### Control Structures ##### Conditionals + Conditionals can either be expressed with the _Logical Relations_, or via explicit `if` expressions. An `if` expression contains at least a _condition_ command and a _then clause_, and optionally the `else` keyword followed by an _else clause_. An _else clause_ may contain another `if` expression instead of a normal block. @@ -237,6 +278,7 @@ The _then clause_ **must** be surrounded by braces, but the _else clause_ may al An `if` expression evaluates either the _then clause_ or (if available) the _else clause_, based on the exit code of the _condition_ command; should the exit code be zero, the _then clause_ will be executed, and if not, the _else clause_ will. ###### Examples + ```sh # Remove a file if it exists, create it otherwise if test -e the_file { @@ -256,6 +298,7 @@ if A { ``` ##### For Loops + For Loops evaluate a sequence of commands once per element in a given list. The shell has two forms of _for loops_, one with an explicitly named iteration variable, and one with an implicitly named one. The general syntax follows the form `for index index_name name in expr { sequence }`, and allows omitting the `index index_name name in` part to implicitly name the variable `it`. @@ -268,6 +311,7 @@ A for-loop evaluates the _sequence_ once per every element in the _expr_, settin The Shell shall cancel the for loop if two consecutive commands are interrupted via SIGINT (\^C), and any other terminating signal aborts the loop entirely. ###### Examples + ```sh # Iterate over every non-hidden file in the current directory, and prepend '1-' to its name. $ for * { mv $it 1-$it } @@ -280,11 +324,13 @@ $ for index i x in * { echo file at index $i is named $x } ``` ##### Infinite Loops + Infinite loops (as denoted by the keyword `loop`) can be used to repeat a block until the block runs `break`, or the loop terminates by external sources (interrupts, program exit, and terminating signals). The behavior regarding SIGINT and other signals is the same as for loops (mentioned above). ###### Examples + ```sh # Keep deleting a file loop { @@ -293,9 +339,11 @@ loop { ``` ##### Subshells + Subshells evaluate a given block in a new instance (fork) of the current shell process. to create a subshell, any valid shell code can be enclosed in braces. ###### Examples + ```sh # Run a block of code in the background, in a subshell, then detach it from the current shell $ { for * { te $it } }& @@ -303,6 +351,7 @@ $ disown ``` ##### Functions + A function is a user-defined entity that can be used as a simple command to execute a compound command, optionally with some parameters. Such a function is defined via the syntax below: @@ -310,7 +359,7 @@ Such a function is defined via the syntax below: function_name(explicitly_named_arguments...) { compound_command } ``` -The function is named `function_name`, and has some explicitly named arguments `explicitly_named_arguments...`, which *must* be supplied by the caller, failure to do so will cause the command to exit with status 1. +The function is named `function_name`, and has some explicitly named arguments `explicitly_named_arguments...`, which _must_ be supplied by the caller, failure to do so will cause the command to exit with status 1. The compound command shall be executed whenever the simple command `function_name` is executed. This execution shall be performed in a new local frame. @@ -319,11 +368,11 @@ Additionally, should the simple command containing the function name be in a pip The passed arguments shall be stored in the special variables `*` and `ARGV`, and the explicitly named arguments shall be set, in order, from the first passed argument onwards. - The exit status of a function simple command shall be the exit status of the last command executed within the command, or 0 if the function has no commands. -The declaration is *not* a command, and will not alter the exit status. +The declaration is _not_ a command, and will not alter the exit status. ###### Examples + ```sh fn(a b c) { echo $a $b $c \( $* \) @@ -334,6 +383,7 @@ $ fn 1 2 3 4 ``` ##### Match Expressions + The pattern matching construct `match` shall choose from a sequence of patterns, and execute the corresponding action in a new frame. The choice is done by matching the result of the _matched expression_ (after expansion) against the _patterns_ (expanded down to either globs or literals). Multiple _patterns_ can be attributed to a single given action by delimiting them with a pipe ('|') symbol. @@ -342,6 +392,7 @@ A _pattern_ (or the series of) may be annotated with an extra `as (...)` clause, The expanded _matched expression_ can optionally be given a name using the `as name` clause after the _matched expression_, with which it may be accessible in the action clauses. ###### Examples + ```sh # Match the result of running 'make_some_value' (which is a list when captured by $(...)) match "$(make_some_value)" as value { @@ -359,32 +410,34 @@ match "$(make_some_value)" { ``` ### History Event Designators + History expansion may be utilized to reuse previously typed words or commands. Such expressions are of the general form `!<event_designator>(:<word_designator>)`, where `event_designator` would select an entry in the shell history, and `word_designator` would select a word (or a range of words) from that entry. -| Event designator | Effect | -| :- | :----- | -| `!` | The immediately preceding command | -| _n_ | The _n_'th entry in the history, starting with 1 as the first entry | +| Event designator | Effect | +| :--------------- | :--------------------------------------------------------------------------- | +| `!` | The immediately preceding command | +| _n_ | The _n_'th entry in the history, starting with 1 as the first entry | | -_n_ | The last _n_'th entry in the history, starting with -1 as the previous entry | -| _str_ | The most recent entry starting with _str_ | -| `?`_str_ | The most recent entry containing _str_ | +| _str_ | The most recent entry starting with _str_ | +| `?`_str_ | The most recent entry containing _str_ | -| Word designator | Effect | -| :-- | :----- | -| _n_ | The word at index _n_, starting with 0 as the first word (usually the command) | -| `^` | The first argument (index 1) | -| `$` | The last argument | -| _x_-_y_ | The range of words starting at _x_ and ending at _y_ (inclusive). _x_ defaults to 0 if omitted | -| `*` | All the arguments. Equivalent to `^`-`$` | -| _x_`*` | The range of words starting at _x_ and ending at the last word (`$`) (inclusive) | -| _x_- | The range of words starting at _x_ and ending at the second to last word (inclusive). _x_ defaults to 0 if omitted | +| Word designator | Effect | +| :-------------- | :----------------------------------------------------------------------------------------------------------------- | +| _n_ | The word at index _n_, starting with 0 as the first word (usually the command) | +| `^` | The first argument (index 1) | +| `$` | The last argument | +| _x_-_y_ | The range of words starting at _x_ and ending at _y_ (inclusive). _x_ defaults to 0 if omitted | +| `*` | All the arguments. Equivalent to `^`-`$` | +| _x_`*` | The range of words starting at _x_ and ending at the last word (`$`) (inclusive) | +| _x_- | The range of words starting at _x_ and ending at the second to last word (inclusive). _x_ defaults to 0 if omitted | Note: The event designator and the word designator should usually be separated by a colon (`:`). This colon can be omitted only if the word designator starts with `^`, `$` or `*` (such as `!1^` for the first argument of the first entry in the history). ## Formal Grammar ### Shell Grammar + ``` toplevel :: sequence? diff --git a/Base/usr/share/man/man5/SystemServer.md b/Base/usr/share/man/man5/SystemServer.md index 31cab7b8099..a14043f76fd 100644 --- a/Base/usr/share/man/man5/SystemServer.md +++ b/Base/usr/share/man/man5/SystemServer.md @@ -10,7 +10,7 @@ SystemServer - services configuration ## Description -SystemServer configuration consists of a list of *services* for it to spawn. +SystemServer configuration consists of a list of _services_ for it to spawn. Each service is configured as a section in the configuration file, where the section name is the service name and the keys inside the section are the options @@ -18,30 +18,31 @@ describing how to launch and manage this service. ## Options -* `Executable` - an executable to spawn. If no explicit executable is specified, SystemServer assumes `/bin/{service name}` (for example, `/bin/WindowServer` for a service named `WindowServer`). -* `Arguments` - a space-separated list of arguments to pass to the service as `argv` (excluding `argv[0]`). By default, SystemServer does not pass any arguments other than `argv[0]`. -* `StdIO` - a path to a file to be passed as standard I/O streams to the service. By default, services run with `/dev/null` for standard I/O. -* `Priority` - the scheduling priority to set for the service, either "low", "normal", or "high". The default is "normal". -* `KeepAlive` - whether the service should be restarted if it exits or crashes. For lazy services, this means the service will get respawned once a new connection is attempted on their socket after they exit or crash. -* `Lazy` - whether the service should only get spawned once a client attempts to connect to their socket. -* `Socket` - a comma-separated list of paths to sockets to create on behalf of the service. For lazy services, SystemServer will actually watch the socket for new connection attempts. See [socket takeover mechanism](#socket-takeover-mechanism) for details on how sockets are passed to services by SystemServer. -* `SocketPermissions` - comma-separated list of (octal) file system permissions for the socket file. The default permissions are 0600. If the number of socket permissions defined is less than the number of sockets defined, then the last defined permission will be used for the remainder of the items in `Socket`. -* `User` - a name of the user to run the service as. This impacts what UID, GID (and extra GIDs) the service processes have. By default, services are run as root. -* `WorkingDirectory` - the working directory in which the service is spawned. By default, services are spawned in the root (`"/"`) directory. -* `SystemModes` - a comma-separated list of system modes in which the service should be enabled. By default, services are only enabled in the "graphical" mode. The current system mode is read from the [kernel command line](help://man/7/boot_parameters#options), and is assumed to be "graphical" if not specified there. -* `Environment` - a space-separated list of "variable=value" pairs to set in the environment for the service. -* `MultiInstance` - whether multiple instances of the service can be running simultaneously. -* `AcceptSocketConnections` - whether SystemServer should accept connections on the socket, and spawn an instance of the service for each client connection. +- `Executable` - an executable to spawn. If no explicit executable is specified, SystemServer assumes `/bin/{service name}` (for example, `/bin/WindowServer` for a service named `WindowServer`). +- `Arguments` - a space-separated list of arguments to pass to the service as `argv` (excluding `argv[0]`). By default, SystemServer does not pass any arguments other than `argv[0]`. +- `StdIO` - a path to a file to be passed as standard I/O streams to the service. By default, services run with `/dev/null` for standard I/O. +- `Priority` - the scheduling priority to set for the service, either "low", "normal", or "high". The default is "normal". +- `KeepAlive` - whether the service should be restarted if it exits or crashes. For lazy services, this means the service will get respawned once a new connection is attempted on their socket after they exit or crash. +- `Lazy` - whether the service should only get spawned once a client attempts to connect to their socket. +- `Socket` - a comma-separated list of paths to sockets to create on behalf of the service. For lazy services, SystemServer will actually watch the socket for new connection attempts. See [socket takeover mechanism](#socket-takeover-mechanism) for details on how sockets are passed to services by SystemServer. +- `SocketPermissions` - comma-separated list of (octal) file system permissions for the socket file. The default permissions are 0600. If the number of socket permissions defined is less than the number of sockets defined, then the last defined permission will be used for the remainder of the items in `Socket`. +- `User` - a name of the user to run the service as. This impacts what UID, GID (and extra GIDs) the service processes have. By default, services are run as root. +- `WorkingDirectory` - the working directory in which the service is spawned. By default, services are spawned in the root (`"/"`) directory. +- `SystemModes` - a comma-separated list of system modes in which the service should be enabled. By default, services are only enabled in the "graphical" mode. The current system mode is read from the [kernel command line](help://man/7/boot_parameters#options), and is assumed to be "graphical" if not specified there. +- `Environment` - a space-separated list of "variable=value" pairs to set in the environment for the service. +- `MultiInstance` - whether multiple instances of the service can be running simultaneously. +- `AcceptSocketConnections` - whether SystemServer should accept connections on the socket, and spawn an instance of the service for each client connection. Note that: -* `Lazy` requires `Socket`, but only one socket must be defined. -* `SocketPermissions` require a `Socket`. -* `MultiInstance` conflicts with `KeepAlive`. -* `AcceptSocketConnections` requires `Socket` (only one), `Lazy`, and `MultiInstance`. + +- `Lazy` requires `Socket`, but only one socket must be defined. +- `SocketPermissions` require a `Socket`. +- `MultiInstance` conflicts with `KeepAlive`. +- `AcceptSocketConnections` requires `Socket` (only one), `Lazy`, and `MultiInstance`. ## Environment -* `SOCKET_TAKEOVER` - set by SystemServer to describe the sockets being passed. +- `SOCKET_TAKEOVER` - set by SystemServer to describe the sockets being passed. ## Socket takeover mechanism @@ -90,4 +91,4 @@ User=window ## See also -* [`SystemServer`(7)](help://man/7/SystemServer) +- [`SystemServer`(7)](help://man/7/SystemServer) diff --git a/Base/usr/share/man/man5/af.md b/Base/usr/share/man/man5/af.md index e7ba9f803d1..984932dd1d9 100644 --- a/Base/usr/share/man/man5/af.md +++ b/Base/usr/share/man/man5/af.md @@ -12,7 +12,7 @@ Application files are a subset of the INI format. They have no easily detectable filemagic and contain application information (App group): | Key | Description | -|---------------|----------------------------------| +| ------------- | -------------------------------- | | Name | name | | Executable | executable path | | Category | category (optional) | @@ -23,7 +23,7 @@ They have no easily detectable filemagic and contain application information (Ap and launcher information (Launcher group, optional): | Key | Description | -|-----------|---------------------------------------| +| --------- | ------------------------------------- | | FileTypes | supported file types separated by ',' | | Protocols | protocols separated by ',' | @@ -42,6 +42,6 @@ Category=Utilities ## See also -- [ini(5)](help://man/5/ini) -- [`Userland/Services/Taskbar/main.cpp`](../../../../../Userland/Services/Taskbar/main.cpp) -- `Launcher::load_handlers` in [`Userland/Services/LaunchServer/Launcher.cpp`](../../../../../Userland/Services/LaunchServer/Launcher.cpp) +- [ini(5)](help://man/5/ini) +- [`Userland/Services/Taskbar/main.cpp`](../../../../../Userland/Services/Taskbar/main.cpp) +- `Launcher::load_handlers` in [`Userland/Services/LaunchServer/Launcher.cpp`](../../../../../Userland/Services/LaunchServer/Launcher.cpp) diff --git a/Base/usr/share/man/man5/clipboard.md b/Base/usr/share/man/man5/clipboard.md index d062274f472..067fda4ef22 100644 --- a/Base/usr/share/man/man5/clipboard.md +++ b/Base/usr/share/man/man5/clipboard.md @@ -5,18 +5,20 @@ clipboard - Data formats specific to Clipboard and drag & drop ## Clipboard The clipboard feature works through the Clipboard server, which generally acts as a global storage or three things: -- a `ByteString` mime type, -- a (potentially large) block of data, shared as an anonymous file, -- a `HashMap<ByteString, ByteString>` of arbitrary metadata, depending on the mime type. + +- a `ByteString` mime type, +- a (potentially large) block of data, shared as an anonymous file, +- a `HashMap<ByteString, ByteString>` of arbitrary metadata, depending on the mime type. See also [`Userland/Libraries/LibGUI/Clipboard.h`](../../../../../Userland/Libraries/LibGUI/Clipboard.h). ## Drag & drop In contrast to the clipboard, the drag & drop feature works through WindowServer, and a bouquet of data is transmitted: -- a `[UTF8] ByteString` to be displayed while dragging, -- a `HashMap<ByteString, ByteBuffer>` map that contains arbitrary data for a variety of possible mime types, -- a `Gfx::ShareableBitmap` to be displayed while dragging + +- a `[UTF8] ByteString` to be displayed while dragging, +- a `HashMap<ByteString, ByteBuffer>` map that contains arbitrary data for a variety of possible mime types, +- a `Gfx::ShareableBitmap` to be displayed while dragging Drag & drop is most prominently supported by File Manager, Spreadsheet, and Terminal. Various applications accept drag & drop to open files. diff --git a/Base/usr/share/man/man5/font.md b/Base/usr/share/man/man5/font.md index ed1a2fe008d..e3dd546394c 100644 --- a/Base/usr/share/man/man5/font.md +++ b/Base/usr/share/man/man5/font.md @@ -18,22 +18,22 @@ and the question mark '?' used as a fallback for unknown glyphs or emojis. The order is big-endian. -| Size | Member name | -|------------|---------------------| -| 4 bytes | Filemagic | -| 1 byte | Glyph width | -| 1 byte | Glyph height | -| 2 bytes | Range mask size | -| 1 byte | Variable width flag | -| 1 byte | Glyph spacing | -| 1 byte | Baseline | -| 1 byte | Mean line | -| 1 byte | Presentation size | -| 2 bytes | Weight | -| 1 byte | Slope | -| 32 bytes | Name | -| 32 bytes | Family | +| Size | Member name | +| -------- | ------------------- | +| 4 bytes | Filemagic | +| 1 byte | Glyph width | +| 1 byte | Glyph height | +| 2 bytes | Range mask size | +| 1 byte | Variable width flag | +| 1 byte | Glyph spacing | +| 1 byte | Baseline | +| 1 byte | Mean line | +| 1 byte | Presentation size | +| 2 bytes | Weight | +| 1 byte | Slope | +| 32 bytes | Name | +| 32 bytes | Family | ## See also -- Format header definition in `Gfx::FontFileHeader` in [`Userland/Libraries/LibGfx/Font/BitmapFont.cpp`](../../../../../Userland/Libraries/LibGfx/Font/BitmapFont.cpp) +- Format header definition in `Gfx::FontFileHeader` in [`Userland/Libraries/LibGfx/Font/BitmapFont.cpp`](../../../../../Userland/Libraries/LibGfx/Font/BitmapFont.cpp) diff --git a/Base/usr/share/man/man5/getopt.md b/Base/usr/share/man/man5/getopt.md index 331efe49e6c..b7bbc8d5dc9 100644 --- a/Base/usr/share/man/man5/getopt.md +++ b/Base/usr/share/man/man5/getopt.md @@ -10,7 +10,7 @@ $ command -o --long-option ## Description -Most programs accept various *options* that configure their behavior to be +Most programs accept various _options_ that configure their behavior to be passed alongside other command-line arguments. Each program accepts its own set of options, though many programs share options in common. @@ -20,7 +20,7 @@ in one argument. Long options have whole strings as their names, are preceded by a double dash, and cannot be grouped. Each option can require (or optionally accept) a **value** (also often -confusingly called an *argument*). Generally, a value for an option, if any, +confusingly called an _argument_). Generally, a value for an option, if any, should be written after the option itself, although the exact syntax for values of short and long options differs. In both cases, the value can be specified as the next command-line argument after the option. For short options, the value @@ -88,4 +88,4 @@ $ command --force -- -argument --another-argument ## See also -* [`getopt`(3)](help://man/3/getopt) +- [`getopt`(3)](help://man/3/getopt) diff --git a/Base/usr/share/man/man5/installed.md b/Base/usr/share/man/man5/installed.md index 42c61d0dac0..7cef2ff3f21 100644 --- a/Base/usr/share/man/man5/installed.md +++ b/Base/usr/share/man/man5/installed.md @@ -4,14 +4,15 @@ installed.db - Package database format ## Description -`/usr/Ports/installed.db` is a file keeping track of installed packages (or ports, respectively). It is a simple text-based format suitable for editing by the port system shell scripts. +`/usr/Ports/installed.db` is a file keeping track of installed packages (or ports, respectively). It is a simple text-based format suitable for editing by the port system shell scripts. Each line of installed.db consists of several space-separated fields. A line may also be empty and therefore ignored. The first field specifies what kind of entry the line contains: -- `auto` specifies a port that is installed automatically, i.e. as a dependency of another port. -- `manual` specifies a port that was installed manually. -- `dependency` does not specify a new port, but the dependencies of a port. The port also has a `manual` or `auto` line somewhere else in the file. + +- `auto` specifies a port that is installed automatically, i.e. as a dependency of another port. +- `manual` specifies a port that was installed manually. +- `dependency` does not specify a new port, but the dependencies of a port. The port also has a `manual` or `auto` line somewhere else in the file. The second field always specifies the port's name. diff --git a/Base/usr/share/man/man5/ipc.md b/Base/usr/share/man/man5/ipc.md index eb61349becc..a2568c5d576 100644 --- a/Base/usr/share/man/man5/ipc.md +++ b/Base/usr/share/man/man5/ipc.md @@ -127,11 +127,11 @@ class ConnectionFromClient final // Client side. namespace MyClient { - + class Client final : public IPC::ConnectionToServer<MyClientEndpoint, MyServerEndpoint> , public MyClientEndpoint {}; - + } ``` @@ -140,5 +140,5 @@ asynchronous functions are prefixed with `async_` and the names of the synchrono ## See also -- [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp`](../../../../../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp) -- [ipc(4)](help://man/4/ipc) (IPC Unix socket documentation) +- [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp`](../../../../../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp) +- [ipc(4)](help://man/4/ipc) (IPC Unix socket documentation) diff --git a/Base/usr/share/man/man5/postcreate.md b/Base/usr/share/man/man5/postcreate.md index a688adef75b..b6df2031165 100644 --- a/Base/usr/share/man/man5/postcreate.md +++ b/Base/usr/share/man/man5/postcreate.md @@ -10,13 +10,13 @@ postcreate - HackStudio postcreate scripts It is possible to define project templates that set up HackStudio projects. These templates can contain custom setup logic in the form of a `*.postcreate` script in the template directory. The script name must match the template's (directory) name. Postcreate scripts are regular shell scripts. They are executed from an indeterminate directory with the following arguments: -- The path to the postcreate script -- The name of the new project -- The path of the new project, i.e. not the parent directory it was created in -- The project name in a form that is safe for C++ namespaces +- The path to the postcreate script +- The name of the new project +- The path of the new project, i.e. not the parent directory it was created in +- The project name in a form that is safe for C++ namespaces The script may error out with a non-zero exit code, but the project is still created. The user is informed of the error. ## See Also -- `ProjectTemplate::create_project` in [`Userland/DevTools/HackStudio/ProjectTemplate.cpp`](../../../../../Userland/DevTools/HackStudio/ProjectTemplate.cpp). +- `ProjectTemplate::create_project` in [`Userland/DevTools/HackStudio/ProjectTemplate.cpp`](../../../../../Userland/DevTools/HackStudio/ProjectTemplate.cpp). diff --git a/Base/usr/share/man/man5/pp.md b/Base/usr/share/man/man5/pp.md index b890a0efd40..08da379daed 100644 --- a/Base/usr/share/man/man5/pp.md +++ b/Base/usr/share/man/man5/pp.md @@ -8,22 +8,22 @@ Pixel Paint files store the drawing data produced by the Pixel Paint application This is a rough overview of the contents of the files: -- width -- height -- layers (optional) - - width - - height - - name - - locationx - - locationy - - opacity_percent - - visible - - selected - - bitmap -- guides (optional) - - offset - - orientation +- width +- height +- layers (optional) + - width + - height + - name + - locationx + - locationy + - opacity_percent + - visible + - selected + - bitmap +- guides (optional) + - offset + - orientation ## See also -- [`Userland/Applications/PixelPaint/Image.cpp`](../../../../../Userland/Applications/PixelPaint/Image.cpp) +- [`Userland/Applications/PixelPaint/Image.cpp`](../../../../../Userland/Applications/PixelPaint/Image.cpp) diff --git a/Base/usr/share/man/man6/2048.md b/Base/usr/share/man/man6/2048.md index 6c67a908aba..1b05080bed1 100644 --- a/Base/usr/share/man/man6/2048.md +++ b/Base/usr/share/man/man6/2048.md @@ -25,9 +25,9 @@ Press `F2` to start a new game. Modify game size, goal and difficulty in the settings. The options are: -* **Board Size** - Set the grid to the chosen number squared. -* **Target Tile** - The winning number, a power of two (e.g. 11 for 2048, 12 for 4096). -* **Evil AI** - Generates new tiles with the worst possible place and value. -* **Temporarily apply changes** - Changes to settings won't persist between sessions. +- **Board Size** - Set the grid to the chosen number squared. +- **Target Tile** - The winning number, a power of two (e.g. 11 for 2048, 12 for 4096). +- **Evil AI** - Generates new tiles with the worst possible place and value. +- **Temporarily apply changes** - Changes to settings won't persist between sessions. Start a new game for changes to apply. diff --git a/Base/usr/share/man/man6/BrickGame.md b/Base/usr/share/man/man6/BrickGame.md index 9b567590d94..c3228a80178 100644 --- a/Base/usr/share/man/man6/BrickGame.md +++ b/Base/usr/share/man/man6/BrickGame.md @@ -15,9 +15,10 @@ $ BrickGame BrickGame is a classic game. Pieces consisting of four small squares each fall from the top of the screen, being fixed in place once they land at the very bottom or on top of other pieces. Once a piece has landed, the next piece will start falling; you can preview this piece on the right side of the screen. By filling an entire row (or line) of squares, that row will be removed and the rows above will shift down. It is also possible to clear multiple lines at once. You can control where and how a piece falls, by moving it left or right, making it move down faster, dropping it down instantly, or rotating it left and right. There are multiple control schemes available for these six basic actions; and the `space bar` always serves as the instant drop key. -- `Left`: Move left, `Right`: Move right, `Up`: Rotate right, `Down`: Move down -- `A`: Move left, `D`: Move right, `W`: Rotate right, `E`: Rotate left, `S`: Move down -- `H`: Move left, `L`: Move right, `K`: Rotate right + +- `Left`: Move left, `Right`: Move right, `Up`: Rotate right, `Down`: Move down +- `A`: Move left, `D`: Move right, `W`: Rotate right, `E`: Rotate left, `S`: Move down +- `H`: Move left, `L`: Move right, `K`: Rotate right The `Escape` and `P` keys pause and unpause the game. diff --git a/Base/usr/share/man/man6/Chess.md b/Base/usr/share/man/man6/Chess.md index 9ef3353e6d6..c59488cd264 100644 --- a/Base/usr/share/man/man6/Chess.md +++ b/Base/usr/share/man/man6/Chess.md @@ -12,6 +12,6 @@ $ Chess ## Description -Chess is an implementation of the 15th century board game. +Chess is an implementation of the 15th century board game. The game can either be played against another human or against the ChessEngine service. diff --git a/Base/usr/share/man/man6/GameOfLife.md b/Base/usr/share/man/man6/GameOfLife.md index 351f3fd9d85..7716da603e0 100644 --- a/Base/usr/share/man/man6/GameOfLife.md +++ b/Base/usr/share/man/man6/GameOfLife.md @@ -16,8 +16,8 @@ GameOfLife is an implementation of John Conway's Game of Life. The game is a cellular automaton where each cell is either dead (grey) or alive (yellow) and will change state in the next tick if any of the following rules are fulfilled: -* An alive cell will die by underpopulation if it has fewer than two neighbors. -* An alive cell will die by overpopulation if it has more than three neighbors. -* A dead cell will come alive by reproduction if it has exactly three neighbors. +- An alive cell will die by underpopulation if it has fewer than two neighbors. +- An alive cell will die by overpopulation if it has more than three neighbors. +- A dead cell will come alive by reproduction if it has exactly three neighbors. Otherwise, it will keep its old state. diff --git a/Base/usr/share/man/man6/Snake.md b/Base/usr/share/man/man6/Snake.md index a60fde084b3..2b9cf2d5dbc 100644 --- a/Base/usr/share/man/man6/Snake.md +++ b/Base/usr/share/man/man6/Snake.md @@ -11,6 +11,7 @@ $ Snake ``` ## Description + `Snake` is an arcade game in which you navigate Snake to eat food. With each item of food you eat Snake grows longer by one block. The challenge is to keep growing without colliding with yourself. Once this happens, the game is over. Use the arrow keys to move Up, Down, Left and Right or alternatively use `W`, `A`, `S`, `D`. diff --git a/Base/usr/share/man/man6/Solitaire.md b/Base/usr/share/man/man6/Solitaire.md index 254373f8a4f..093b3d9cebc 100644 --- a/Base/usr/share/man/man6/Solitaire.md +++ b/Base/usr/share/man/man6/Solitaire.md @@ -14,9 +14,9 @@ $ Solitaire Solitaire is an implementation of the classic solitaire card game Klondike, which became very popular in digital form during the 90s after being included in Microsoft Windows OS. -The game is played with a standard 52-card deck. Objective of the game is completing four distinct ordered sequences of cards (*foundation*), one per suit, from Ace to King. +The game is played with a standard 52-card deck. Objective of the game is completing four distinct ordered sequences of cards (_foundation_), one per suit, from Ace to King. -After shuffling the deck, the game starts, with a setup (*tableau*) of seven vertical piles of cards, increasingly longer: the first pile is one card long, the seventh is seven cards long. Only the top card of each pile is upturned and accessible. The unused cards (*stock*) are kept aside, covered. +After shuffling the deck, the game starts, with a setup (_tableau_) of seven vertical piles of cards, increasingly longer: the first pile is one card long, the seventh is seven cards long. Only the top card of each pile is upturned and accessible. The unused cards (_stock_) are kept aside, covered. Cards can be moved from one pile of the tableau to another only by building contiguous descending sequences of alternate color: for example, King of Diamonds / Queen of Clubs, or 5 of Spades / 4 of Diamonds / 3 of Clubs. Within that rule, multiple cards can be moved at the same time. If one of the seven piles is empty, a new pile can be built there, starting with a King. @@ -24,11 +24,10 @@ The top card from any pile can be detached and added to the foundation, if it is When a new card reaches the top of the pile, it is turned face up. A card which is upturned is never turned face down, even if it is not at the top of the pile anymore. -When no more moves are available, one (or, in a different variant, three) card(s) is taken from the stock and turned up. It can be added either to the tableau piles or to the foundation; if neither is possible, it goes to the waste. +When no more moves are available, one (or, in a different variant, three) card(s) is taken from the stock and turned up. It can be added either to the tableau piles or to the foundation; if neither is possible, it goes to the waste. The game can conclude in one of two different ways: (a) the game is won if all 52 cards are moved to the foundation (b) the game is lost if no more progress can be achieved towards the foundation. - ## Examples foundation @@ -41,14 +40,12 @@ The game can conclude in one of two different ways: (a) the game is won if all 5 Basic move: the ♠ Q can be shifted from pile 1 to pile 2, since (♦ K - ♠ Q) is a valid descending sequence. Now the ♥ 3 can be taken from pile 1 and moved to the foundation, because it is the next card in the Hearts sequence after the Two. - pile 1 pile 2 ... ♥ 3 ♦ K ♠ Q ♥ J -Multiple-card move: same as before, except the Q and J on pile 1 must be moved together to pile 2 to produce the sequence (♦ K - ♠ Q - ♥ J). - +Multiple-card move: same as before, except the Q and J on pile 1 must be moved together to pile 2 to produce the sequence (♦ K - ♠ Q - ♥ J). pile 1 pile 2 ... ♥ 3 ♦ K diff --git a/Base/usr/share/man/man6/Spider.md b/Base/usr/share/man/man6/Spider.md index eb819b64ac2..5a0f18a5273 100644 --- a/Base/usr/share/man/man6/Spider.md +++ b/Base/usr/share/man/man6/Spider.md @@ -16,7 +16,7 @@ Spider is an implementation of the classic solitaire card game with the same nam In this version, the game is played with 104 cards, forming 8 complete (A to K) instances of either 2 different suits or a single suit, as chosen from the in-game menu. -After shuffling together the cards, the game starts, with a setup (*tableau*) of 54 cards over 10 vertical piles. Only the top card of each pile is upturned and accessible. The unused 50 cards (*stock*) are kept aside, covered, and dealt 10 at a time (1 per pile), when no more moves are possible on the current tableau. +After shuffling together the cards, the game starts, with a setup (_tableau_) of 54 cards over 10 vertical piles. Only the top card of each pile is upturned and accessible. The unused 50 cards (_stock_) are kept aside, covered, and dealt 10 at a time (1 per pile), when no more moves are possible on the current tableau. Objective of the game is removing all the cards from the tableau and stock. @@ -26,22 +26,18 @@ A complete King-to-Ace sequence of the same suit can be removed from the tableau When a new card reaches the top of the pile, it is turned face up. A card which is upturned is never turned face down, even if it is not at the top of the pile anymore. -When no more moves are available, 10 more cards are moved from the stock to the piles, 1 per pile, and turned face up. +When no more moves are available, 10 more cards are moved from the stock to the piles, 1 per pile, and turned face up. The game can conclude in one of two different ways: (a) the game is won if all cards are removed from the tableau, and the stock is empty (b) the game is lost if no more progress can be achieved. - ## Examples - - pile 1 pile 2 ... ♥ 3 ♦ K ♠ Q Basic move: the ♠ Q can be shifted from pile 1 to pile 2, since (K - Q) is a valid sequence. - pile 1 pile 2 ... ♥ 3 ♦ K ♠ Q @@ -49,12 +45,9 @@ Basic move: the ♠ Q can be shifted from pile 1 to pile 2, since (K - Q) is a v Multiple-card move: same as before, except the Q and J on pile 1, constituting a valid in-suit sequence, can be moved together to pile 2 to produce (K - Q - J) sequence. - - pile 1 pile 2 ... ♥ 3 ♥ K ♠ K ♥ J No move: no contiguous descending sequence can be produced here. - diff --git a/Base/usr/share/man/man7/Audio-subsystem.md b/Base/usr/share/man/man7/Audio-subsystem.md index bca4572861e..fed83704769 100644 --- a/Base/usr/share/man/man7/Audio-subsystem.md +++ b/Base/usr/share/man/man7/Audio-subsystem.md @@ -59,12 +59,12 @@ LibDSP also contains a collection of general signal processing primitives, such This is a non-exhaustive list of applications that use audio. Most of these follow the good practices laid out in this manual page and may serve as a template for new audio applications. -* **Piano** is a sequencer/tracker and synthesizer. -* [**aplay**](help://man/1/aplay) is a command line audio file playback utility. -* **SoundPlayer** is a UI audio file player with extra features such as playlist support and audio visualizations. -* [**asctl**](help://man/1/asctl) is a command line audio server control utility. -* **Applets/Audio** (AudioApplet) is a taskbar applet for setting audio parameters through a UI. -* The [Browser](help://man/1/Applications/Browser) can play audio on websites. +- **Piano** is a sequencer/tracker and synthesizer. +- [**aplay**](help://man/1/aplay) is a command line audio file playback utility. +- **SoundPlayer** is a UI audio file player with extra features such as playlist support and audio visualizations. +- [**asctl**](help://man/1/asctl) is a command line audio server control utility. +- **Applets/Audio** (AudioApplet) is a taskbar applet for setting audio parameters through a UI. +- The [Browser](help://man/1/Applications/Browser) can play audio on websites. ### Volume @@ -80,11 +80,11 @@ SerenityOS's audio system uses a variety of sample rates in different layers of ## Files -* [/dev/audio](help://man/4/audio) -* AudioApplet and AudioServer have settings which are managed by ConfigServer. -* `/tmp/session/%sid/portal/audio`: AudioServer's client IPC socket +- [/dev/audio](help://man/4/audio) +- AudioApplet and AudioServer have settings which are managed by ConfigServer. +- `/tmp/session/%sid/portal/audio`: AudioServer's client IPC socket ## See also -* [asctl](help://man/1/asctl) -* [aplay](help://man/1/aplay) +- [asctl](help://man/1/asctl) +- [aplay](help://man/1/aplay) diff --git a/Base/usr/share/man/man7/Help-index.md b/Base/usr/share/man/man7/Help-index.md index 8883c6c74d1..70393a9b83c 100644 --- a/Base/usr/share/man/man7/Help-index.md +++ b/Base/usr/share/man/man7/Help-index.md @@ -13,9 +13,10 @@ There's also a full-text search option under the **Search** tab. If you want more information on the structure of the manual system, take a look at [`man(7)`](help://man/7/man). ### Getting Started -* [Keyboard Shortcuts](help://man/7/KeyboardShortcuts) -* [Tips and Tricks](help://man/7/Tips-and-Tricks) + +- [Keyboard Shortcuts](help://man/7/KeyboardShortcuts) +- [Tips and Tricks](help://man/7/Tips-and-Tricks) --- -Thank you for using ***SerenityOS Help!*** \ No newline at end of file +Thank you for using **_SerenityOS Help!_** diff --git a/Base/usr/share/man/man7/KeyboardShortcuts.md b/Base/usr/share/man/man7/KeyboardShortcuts.md index 5006a46a56d..95784e3907f 100644 --- a/Base/usr/share/man/man7/KeyboardShortcuts.md +++ b/Base/usr/share/man/man7/KeyboardShortcuts.md @@ -1,24 +1,29 @@ ![Keyboard Icon](/res/icons/32x32/app-keyboard-settings.png) ## Name + Keyboard Shortcuts ## Description + This is a collection of common keyboard shortcuts in SerenityOS. ### Keywords -* `Super` means the ⊞ Windows or ⌘ Command key (and is sometimes called 'Meta' on Linux) -* `Alt` is equivalent to ⌥ Option on macOS + +- `Super` means the ⊞ Windows or ⌘ Command key (and is sometimes called 'Meta' on Linux) +- `Alt` is equivalent to ⌥ Option on macOS ## General + | Shortcut | Action | -|---------------|------------------------------------------------------------------------------------------------| +| ------------- | ---------------------------------------------------------------------------------------------- | | `Super` | Open the System Menu (navigate via arrow keys) | | `Super+Space` | Open [Assistant](help://man/1/Applications/Assistant) (system search and application launcher) | ### Window Management + | Shortcut | Action | -|--------------------------|-----------------------------------------------------------------------| +| ------------------------ | --------------------------------------------------------------------- | | `Super+Up` | Maximize the window | | `Super+Down` | Minimize the window (or un-maximize) | | `Super+Left` | Snap window to left half of the screen | @@ -34,8 +39,9 @@ This is a collection of common keyboard shortcuts in SerenityOS. | `Shift+Ctrl+Alt+Arrows` | Move Workspace with the active window | ### Common within Applications + | Shortcut | Action | -|----------------|---------------------------------------------------------------| +| -------------- | ------------------------------------------------------------- | | `Ctrl+Z` | Undo | | `Ctrl+Shift+Z` | Redo | | `Ctrl+A` | Select All | @@ -55,15 +61,18 @@ This is a collection of common keyboard shortcuts in SerenityOS. | `Alt+F4` | Quit | ### Text Input + | Shortcut | Action | -|------------------|-------------------------------------------------------| +| ---------------- | ----------------------------------------------------- | | `Ctrl+Alt+Space` | Emoji Picker | | `Shift+Alt` | Hold `Shift` and press `Alt` to cycle through keymaps | ### Accessibility + | Shortcut | Action | -|-----------|------------------| +| --------- | ---------------- | | `Super+H` | Highlight Cursor | ## See also -* [Tips and Tricks](help://man/7/Tips-and-Tricks) \ No newline at end of file + +- [Tips and Tricks](help://man/7/Tips-and-Tricks) diff --git a/Base/usr/share/man/man7/Mitigations.md b/Base/usr/share/man/man7/Mitigations.md index cd53e37f1c6..0a5ab7f37f1 100644 --- a/Base/usr/share/man/man7/Mitigations.md +++ b/Base/usr/share/man/man7/Mitigations.md @@ -17,6 +17,7 @@ to collect and describe the mitigations in one centralized place. of userspace code with kernel privileges. It was enabled in the following [commit](https://github.com/SerenityOS/serenity/commit/8602fa5b49aa4e2b039764a14698f0baa3ad0532): + ``` commit 8602fa5b49aa4e2b039764a14698f0baa3ad0532 Author: Andreas Kling <awesomekling@gmail.com> @@ -49,6 +50,7 @@ These instructions let user mode code query the addresses of various kernel stru meaning that they leak kernel addresses that can be exploited to defeat ASLR. It was enabled in the following [commit](https://github.com/SerenityOS/serenity/commit/9c0836ce97ae36165abd8eb5241bb5239af3a756): + ``` commit 9c0836ce97ae36165abd8eb5241bb5239af3a756 Author: Andreas Kling <awesomekling@gmail.com> @@ -96,16 +98,18 @@ Kernel: Add a basic implementation of unveil() It allows a program to be placed inside a lightweight OS-level virtualization environment. Current restrictions on jailed processes (configurable when creating a Jail): -- Process ID view isolation, being limited (both in `/proc` and `/sys/kernel/processes`) to only processes that share the same jail. + +- Process ID view isolation, being limited (both in `/proc` and `/sys/kernel/processes`) to only processes that share the same jail. Special restrictions on filesystem also apply: -- Write access is forbidden to the `/sys/kernel/power_state` node. -- Read accesses is forbidden by default to all nodes in `/sys/kernel` directory, except for: + +- Write access is forbidden to the `/sys/kernel/power_state` node. +- Read accesses is forbidden by default to all nodes in `/sys/kernel` directory, except for: `df`, `interrupts`, `keymap`, `memstat`, `processes`, `stats` and `uptime`. -- Write access is forbidden to kernel configuration variables (which are located in `/sys/kernel/conf`). -- Open access is forbidden to all device nodes except for `/dev/full`, `/dev/null`, `/dev/zero`, `/dev/random` and various +- Write access is forbidden to kernel configuration variables (which are located in `/sys/kernel/conf`). +- Open access is forbidden to all device nodes except for `/dev/full`, `/dev/null`, `/dev/zero`, `/dev/random` and various other TTY/PTY devices (not including Kernel virtual consoles). -- Executing SUID binaries is forbidden. +- Executing SUID binaries is forbidden. It was first added in the following [commit](https://github.com/SerenityOS/serenity/commit/5e062414c11df31ed595c363990005eef00fa263), for kernel support, and the following commits added basic userspace utilities: @@ -222,6 +226,7 @@ It can find various issues, including integer overflows, out-of-bounds array accesses, type corruption, and more. It was first enabled in the following [commit](https://github.com/SerenityOS/serenity/commit/d44be968938ecf95023351a358c43c4957638d87): + ``` commit d44be968938ecf95023351a358c43c4957638d87 Author: Andreas Kling <kling@serenityos.org> @@ -243,6 +248,7 @@ With this mitigation it is now more difficult to craft a kernel exploit to do so like disabling SMEP / SMAP. It was first enabled in the following [commit](https://github.com/SerenityOS/serenity/commit/6136faa4ebf6a878606f33bc03c5e62de9d5e662): + ``` commit 6136faa4ebf6a878606f33bc03c5e62de9d5e662 Author: Andreas Kling <kling@serenityos.org> @@ -263,6 +269,7 @@ to make that memory read-only before passing control to the main executable. This prevents attackers from overwriting the [Global Offset Table (GOT)](https://en.wikipedia.org/wiki/Global_Offset_Table). It was first enabled for executables in the following [commit](https://github.com/SerenityOS/serenity/commit/fa4c249425a65076ca04a3cb0c173d49472796fb): + ``` commit fa4c249425a65076ca04a3cb0c173d49472796fb Author: Andreas Kling <kling@serenityos.org> @@ -272,6 +279,7 @@ LibELF+Userland: Enable RELRO for all userland executables :^) ``` Shared libraries were enabled in a follow-up [commit](https://github.com/SerenityOS/serenity/commit/713b3b36be4f659e58e253b6c830509898dbd2fa): + ``` commit 713b3b36be4f659e58e253b6c830509898dbd2fa Author: Andreas Kling <kling@serenityos.org> @@ -288,6 +296,7 @@ style attacks by generating code that probes the stack in page-sized increments This prevents attackers from using a large stack allocation to "jump over" the stack guard page into adjacent memory. It was first enabled in the following [commit](https://github.com/SerenityOS/serenity/commit/7142562310e631156d1f64aff22f068ae2c48a5e): + ``` commit 7142562310e631156d1f64aff22f068ae2c48a5e Author: Andreas Kling <kling@serenityos.org> @@ -337,6 +346,7 @@ Date: Fri Jan 1 15:27:42 2021 -0800 Build + LibC: Enable -fstack-protector-strong in user space ``` + ### Protected Kernel Process Data The kernel applies a exploit mitigation technique where vulnerable data @@ -346,6 +356,7 @@ or updated. This means that an attacker needs more than an arbitrary kernel write primitive to be able to elevate a process to root for example. It was first enabled in the following [commit](https://github.com/SerenityOS/serenity/commit/cbcf891040e9921ff628fdda668c9738f358a178): + ``` commit cbcf891040e9921ff628fdda668c9738f358a178 Author: Andreas Kling <kling@serenityos.org> @@ -423,5 +434,5 @@ Kernel: Enable -ftrivial-auto-var-init as a security mitigation ## See also -* [`unveil`(2)](help://man/2/unveil) -* [`pledge`(2)](help://man/2/pledge) +- [`unveil`(2)](help://man/2/unveil) +- [`pledge`(2)](help://man/2/pledge) diff --git a/Base/usr/share/man/man7/Shell-vars.md b/Base/usr/share/man/man7/Shell-vars.md index 811098ea018..eeb55c2c67d 100644 --- a/Base/usr/share/man/man7/Shell-vars.md +++ b/Base/usr/share/man/man7/Shell-vars.md @@ -21,14 +21,14 @@ The value of this variable is used to join lists or split strings into lists, it The value of this variable is used to determine which entries are kept in the Shell's history, both regarding the current active session and when writing the history to disk on exit. -- `ignorespace`: Entries starting with one or more space characters are ignored -- `ignoredups`: Consecutive duplicate entries are ignored -- `ignoreboth`: The behavior of `ignorespace` and `ignoredups` is combined -- If the variable is unset (this is the default) or has any other value than the above, no entries will be excluded from history. +- `ignorespace`: Entries starting with one or more space characters are ignored +- `ignoredups`: Consecutive duplicate entries are ignored +- `ignoreboth`: The behavior of `ignorespace` and `ignoredups` is combined +- If the variable is unset (this is the default) or has any other value than the above, no entries will be excluded from history. Note: This variable is respected by every program using `Line::Editor`, e.g. [`js`(1)](help://man/1/js). -`HISTFILE` (environment) +`HISTFILE` (environment) The value of this variable is used as the Shell's history file path, both for reading history at startup and writing history on exit. Its default value is `~/.history`. @@ -56,20 +56,21 @@ Also note that the line editor will re-evaluate the keybindings and sync them wh `PROMPT` (environment) The value of this variable is used to generate a prompt, the following escape sequences can be used literally inside the value, and they would expand to their respective values: -- `\\a`: bell character (behavior depends on terminal) -- `\\e`: escape character (`0x1b`) -- `\\h`: the current hostname -- `\\p`: the string '$' (or '#' if the user is 'root') -- `\\u`: the current username -- `\\w`, `\\W`: a collapsed path (relative to home) to the current directory. If an integer follows the `\\`, it specifies the number of trailing components of the path to show; if 'w' is used instead of 'W', removed components are shown with ellipsis ("...") -- `\\X`: reset style (foreground and background color, etc) -- `\\t`: current time in the 24-hour format HH:MM:SS -- `\\T`: current time in the 12-hour format HH:MM -- `\\@`: current time in the 12-hour format HH:MM AM/PM -- `\\D{format}`: current time, where the string _format_ is passed on to `Core::DateTime::to_string`. If _format_ is empty, a default format string is chosen. -- `\\j`: the number of jobs currently managed by the shell -- `\\!`: the history number of the next command to be run -- `\\\\`: a backslash + +- `\\a`: bell character (behavior depends on terminal) +- `\\e`: escape character (`0x1b`) +- `\\h`: the current hostname +- `\\p`: the string '$' (or '#' if the user is 'root') +- `\\u`: the current username +- `\\w`, `\\W`: a collapsed path (relative to home) to the current directory. If an integer follows the `\\`, it specifies the number of trailing components of the path to show; if 'w' is used instead of 'W', removed components are shown with ellipsis ("...") +- `\\X`: reset style (foreground and background color, etc) +- `\\t`: current time in the 24-hour format HH:MM:SS +- `\\T`: current time in the 12-hour format HH:MM +- `\\@`: current time in the 12-hour format HH:MM AM/PM +- `\\D{format}`: current time, where the string _format_ is passed on to `Core::DateTime::to_string`. If _format_ is empty, a default format string is chosen. +- `\\j`: the number of jobs currently managed by the shell +- `\\!`: the history number of the next command to be run +- `\\\\`: a backslash Any other escaped character shall be ignored. diff --git a/Base/usr/share/man/man7/SystemServer.md b/Base/usr/share/man/man7/SystemServer.md index bd47a0064c6..ae64a42eaf4 100644 --- a/Base/usr/share/man/man7/SystemServer.md +++ b/Base/usr/share/man/man7/SystemServer.md @@ -8,15 +8,15 @@ SystemServer is the first userspace process to be started by the kernel on boot. Its main responsibility is spawning all the other servers and other programs that need to be autostarted (referred to as **services**). -A service can be configured to be *kept alive*, in which case SystemServer will -respawn it if it exits or crashes. A service may also be configured as *lazy*, +A service can be configured to be _kept alive_, in which case SystemServer will +respawn it if it exits or crashes. A service may also be configured as _lazy_, in which case SystemServer won't spawn it immediately, but only once a client connects to its socket (see **Socket takeover** below). ## Socket takeover SystemServer can be configured to set up a socket on behalf of a service -(typically, an *IPC portal* socket inside `/tmp/portal/`). SystemServer sets up +(typically, an _IPC portal_ socket inside `/tmp/portal/`). SystemServer sets up the configured sockets before spawning any services, preventing any races between socket creation and the client trying to connect to those sockets. @@ -34,11 +34,11 @@ children. LibCore provides `Core::LocalServer::take_over_from_system_server()` method that performs the service side of the socket takeover automatically. -If a service is configured as *lazy*, SystemServer will actually listen on the +If a service is configured as _lazy_, SystemServer will actually listen on the socket it sets up for the service, and only spawn the service once a client tries to connect to the socket. The service should then start up and accept the connection. This all happens transparently to the client. If a lazy service is -configured to be *kept alive*, it can even exit after some period of inactivity; +configured to be _kept alive_, it can even exit after some period of inactivity; in this case SystemServer will respawn it again once there is a new connection to its socket. @@ -48,4 +48,4 @@ the accepted socket to the service process. ## See also -* [`SystemServer`(5)](help://man/5/SystemServer) +- [`SystemServer`(5)](help://man/5/SystemServer) diff --git a/Base/usr/share/man/man7/Tips-and-Tricks.md b/Base/usr/share/man/man7/Tips-and-Tricks.md index 564ee16bd7b..34c6f86a65c 100644 --- a/Base/usr/share/man/man7/Tips-and-Tricks.md +++ b/Base/usr/share/man/man7/Tips-and-Tricks.md @@ -1,59 +1,72 @@ ![Welcome Icon](/res/icons/32x32/app-welcome.png) ## Name + Tips and Tricks ## Description + This is a list of useful tips and tricks to help you make the most out of SerenityOS. ## General -* When on the Desktop or in File Manager, start typing the name of an item to select it. -* Bold text in context menus hints at the default behavior of a double-click. -* Hold `Ctrl` to accelerate mouse wheel interaction with sliders and spin boxes. -* Hold `Ctrl` while activating a menu item to prevent that menu from closing. -* Many applications can open a compatible file if you drag-and-drop it into their window. -* Change default file and protocol associations in `~/.config/LaunchServer.ini`. + +- When on the Desktop or in File Manager, start typing the name of an item to select it. +- Bold text in context menus hints at the default behavior of a double-click. +- Hold `Ctrl` to accelerate mouse wheel interaction with sliders and spin boxes. +- Hold `Ctrl` while activating a menu item to prevent that menu from closing. +- Many applications can open a compatible file if you drag-and-drop it into their window. +- Change default file and protocol associations in `~/.config/LaunchServer.ini`. ### Window Management -* Double-click a window's title bar to maximize it. -* Click on a window's icon to open the window's context menu. -* Double-click on the edge of an application's window to maximize it in that direction. -* Middle-click on a window's maximize button to extend the window vertically (this can be undone in the same way). -* Drag resizable windows to any side or corner of the screen to automatically resize them to fill half or one-quarter of the screen. -* Right-click on the Workspace Picker applet and select 'Workspace Settings' to easily customize the number and layout of Workspaces (virtual desktops). + +- Double-click a window's title bar to maximize it. +- Click on a window's icon to open the window's context menu. +- Double-click on the edge of an application's window to maximize it in that direction. +- Middle-click on a window's maximize button to extend the window vertically (this can be undone in the same way). +- Drag resizable windows to any side or corner of the screen to automatically resize them to fill half or one-quarter of the screen. +- Right-click on the Workspace Picker applet and select 'Workspace Settings' to easily customize the number and layout of Workspaces (virtual desktops). ### Fun -* It can help to get a second pair of `$ Eyes` on a problem… or fifty: `$ Eyes -n 100`. + +- It can help to get a second pair of `$ Eyes` on a problem… or fifty: `$ Eyes -n 100`. ## Applications ### [Assistant](help://man/1/Applications/Assistant) -* Assistant can help you to quickly find files and launch applications. Open it with `Super+Space`. -* Enter a URL to open it in the web browser, e.g. `serenityos.org`. -* Perform quick calculations by typing the equal sign (=) followed by a mathematical expression, e.g. `=22*101`. Press Return to copy the result. -* Run commands in the terminal by prefixing them with a dollar sign ($), e.g. `$ uname -a`. + +- Assistant can help you to quickly find files and launch applications. Open it with `Super+Space`. +- Enter a URL to open it in the web browser, e.g. `serenityos.org`. +- Perform quick calculations by typing the equal sign (=) followed by a mathematical expression, e.g. `=22*101`. Press Return to copy the result. +- Run commands in the terminal by prefixing them with a dollar sign ($), e.g. `$ uname -a`. ### [Browser](help://man/1/Applications/Browser) -* Browser has built-in content filtering, which can be used for ad blocking. Update the filters in `~/.config/BrowserContentFiltering.txt`. + +- Browser has built-in content filtering, which can be used for ad blocking. Update the filters in `~/.config/BrowserContentFiltering.txt`. ### Keyboard Mapper -* Create and edit custom keymaps with `$ KeyboardMapper`. + +- Create and edit custom keymaps with `$ KeyboardMapper`. ### Run -* The Run dialog accepts all [Shell](help://man/5/Shell) commands. + +- The Run dialog accepts all [Shell](help://man/5/Shell) commands. ### [Terminal](help://man/1/Applications/Terminal) -* Some of the bold or underlined text in Terminal can be double-clicked to open or right-clicked for additional actions. - * For example, right-click on a file or folder and select 'Copy URL' to copy the path. -* Many Serenity applications already have convenient aliases. Use `$ cat /etc/shellrc` to view them. + +- Some of the bold or underlined text in Terminal can be double-clicked to open or right-clicked for additional actions. + - For example, right-click on a file or folder and select 'Copy URL' to copy the path. +- Many Serenity applications already have convenient aliases. Use `$ cat /etc/shellrc` to view them. ### [Text Editor](help://man/1/Applications/TextEditor) -* Text files can be dragged directly from Terminal and dropped on Text Editor to open them. -* Text Editor has multiple viewing modes. You can edit HTML or Markdown and live preview it at the same time. + +- Text files can be dragged directly from Terminal and dropped on Text Editor to open them. +- Text Editor has multiple viewing modes. You can edit HTML or Markdown and live preview it at the same time. ## Development -* Supplying `# profile` with a process identifier (PID) of `-1` as root enables systemwide profiling. -* Easily transfer files from QEMU to your host machine by using the built-in web server. In the terminal enter `ws .` to start a WebServer instance for the current working directory. Then open `localhost:8000` on your host machine. + +- Supplying `# profile` with a process identifier (PID) of `-1` as root enables systemwide profiling. +- Easily transfer files from QEMU to your host machine by using the built-in web server. In the terminal enter `ws .` to start a WebServer instance for the current working directory. Then open `localhost:8000` on your host machine. ## See also -* [Keyboard Shortcuts](help://man/7/KeyboardShortcuts) + +- [Keyboard Shortcuts](help://man/7/KeyboardShortcuts) diff --git a/Base/usr/share/man/man7/boot_parameters.md b/Base/usr/share/man/man7/boot_parameters.md index 6eed6be21bf..906254bb14b 100644 --- a/Base/usr/share/man/man7/boot_parameters.md +++ b/Base/usr/share/man/man7/boot_parameters.md @@ -15,88 +15,87 @@ trailer can be omitted for specific parameters. List of options: -* **`acpi`** - This parameter expects one of the following values. **`on`** - Boot with full ACPI support, using ACPI - Machine Language interpretation (default). **`limited`** - Boot with limited ACPI support. **`off`** - Don't initialize ACPI at all. +- **`acpi`** - This parameter expects one of the following values. **`on`** - Boot with full ACPI support, using ACPI + Machine Language interpretation (default). **`limited`** - Boot with limited ACPI support. **`off`** - Don't initialize ACPI at all. -* **`ahci_reset_mode`** - This parameter expects one of the following values. **`controllers`** - Reset just the AHCI controller on boot (default). - **`aggressive`** - Reset the AHCI controller, and all AHCI ports on boot. +- **`ahci_reset_mode`** - This parameter expects one of the following values. **`controllers`** - Reset just the AHCI controller on boot (default). + **`aggressive`** - Reset the AHCI controller, and all AHCI ports on boot. -* **`boot_prof`** - If present on the command line, global system profiling will be enabled - as soon as possible during the boot sequence. Allowing you to profile startup of all applications. +- **`boot_prof`** - If present on the command line, global system profiling will be enabled + as soon as possible during the boot sequence. Allowing you to profile startup of all applications. -* **`disable_physical_storage`** - If present on the command line, neither AHCI, or IDE controllers will be initialized on boot. +- **`disable_physical_storage`** - If present on the command line, neither AHCI, or IDE controllers will be initialized on boot. -* **`disable_ps2_mouse`** - If present on the command line, no PS2 mouse will be attached. - -* **`disable_uhci_controller`** - If present on the command line, the UHCI controller will not be initialized on boot. +- **`disable_ps2_mouse`** - If present on the command line, no PS2 mouse will be attached. +- **`disable_uhci_controller`** - If present on the command line, the UHCI controller will not be initialized on boot. -* **`disable_virtio`** - If present on the command line, virtio devices will not be detected, and initialized on boot. +- **`disable_virtio`** - If present on the command line, virtio devices will not be detected, and initialized on boot. -* **`early_boot_console`** - This parameter expects **`on`** or **`off`** and is by default set to **`on`**. - When set to **`off`**, the kernel will not initialize any early console to show kernel dmesg output. - When set to **`on`**, the kernel will try to initialize either a text mode console (if VGA text mode was detected) - or framebuffer console, based on what the Multiboot bootloader specified on the physical address, width, height - and bit color depth. +- **`early_boot_console`** - This parameter expects **`on`** or **`off`** and is by default set to **`on`**. + When set to **`off`**, the kernel will not initialize any early console to show kernel dmesg output. + When set to **`on`**, the kernel will try to initialize either a text mode console (if VGA text mode was detected) + or framebuffer console, based on what the Multiboot bootloader specified on the physical address, width, height + and bit color depth. -* **`enable_ioapic`** - This parameter expects **`on`** or **`off`** and is by default set to **`on`**. - When set to **`off`**, the kernel will initialize the two i8259 PICs. - When set to **`on`**, the kernel will try to initialize the IOAPIC (or IOAPICs if there's more than one), - but only if **`acpi`** is set to **`limited`** or **`on`**, and a `MADT` (APIC) table is available. - Otherwise, the kernel will fallback to use the i8259 PICs. +- **`enable_ioapic`** - This parameter expects **`on`** or **`off`** and is by default set to **`on`**. + When set to **`off`**, the kernel will initialize the two i8259 PICs. + When set to **`on`**, the kernel will try to initialize the IOAPIC (or IOAPICs if there's more than one), + but only if **`acpi`** is set to **`limited`** or **`on`**, and a `MADT` (APIC) table is available. + Otherwise, the kernel will fallback to use the i8259 PICs. -* **`graphics_subsystem_mode`** - This parameter expects one of the following values. **`on`**- Boot into the graphical environment if possible (default). **`off`** - Boot into text mode, don't initialize any driver. **`limited`** - Boot into the pre-defined framebuffer that the bootloader -has set up before booting the Kernel, don't initialize any driver. +- **`graphics_subsystem_mode`** - This parameter expects one of the following values. **`on`**- Boot into the graphical environment if possible (default). **`off`** - Boot into text mode, don't initialize any driver. **`limited`** - Boot into the pre-defined framebuffer that the bootloader + has set up before booting the Kernel, don't initialize any driver. -* **`hpet`** - This parameter expects one of the following values. **`periodic`** - The High Precision Event Timer should - be configured in a periodic mode. **`nonperiodic`** - The High Precision Event Timer should eb configure din non-periodic mode. +- **`hpet`** - This parameter expects one of the following values. **`periodic`** - The High Precision Event Timer should + be configured in a periodic mode. **`nonperiodic`** - The High Precision Event Timer should eb configure din non-periodic mode. -* **`init`** - This parameter expects the fully qualified path to the init program the Kernel should launch after boot. +- **`init`** - This parameter expects the fully qualified path to the init program the Kernel should launch after boot. This defaults to [`SystemServer`(7)](help://man/7/SystemServer). -* **`init_args`** - This parameter expects a set of arguments to pass to the **`init`** program. - The value should be a set of strings separated by `,` characters. +- **`init_args`** - This parameter expects a set of arguments to pass to the **`init`** program. + The value should be a set of strings separated by `,` characters. -* **`i8042_presence_mode`** - This parameter expects one of the following values: - **`aggressive-test`** - The i8042 initialization sequence should only try an aggressive presence test. - **`auto`** - The i8042 initialization sequence should try to check if ACPI says i8042 exists, and if not an aggressive presence test should take place to determine presence. - **`none`** - Assume there's no i8042 controller in the system. - **`force`** - Assume there's i8042 controller in the system. +- **`i8042_presence_mode`** - This parameter expects one of the following values: + **`aggressive-test`** - The i8042 initialization sequence should only try an aggressive presence test. + **`auto`** - The i8042 initialization sequence should try to check if ACPI says i8042 exists, and if not an aggressive presence test should take place to determine presence. + **`none`** - Assume there's no i8042 controller in the system. + **`force`** - Assume there's i8042 controller in the system. -* **`i8042_first_port_translation`** - This parameter expects **`on`** or **`off`** and is by default set to **`off`**. - When set to **`off`**, the kernel will not enable first PS2 port translation. - When set to **`on`**, the kernel will enable first PS2 port translation. +- **`i8042_first_port_translation`** - This parameter expects **`on`** or **`off`** and is by default set to **`off`**. + When set to **`off`**, the kernel will not enable first PS2 port translation. + When set to **`on`**, the kernel will enable first PS2 port translation. -* **`panic`** - This parameter expects **`halt`** or **`shutdown`**. This is particularly useful in CI contexts. +- **`panic`** - This parameter expects **`halt`** or **`shutdown`**. This is particularly useful in CI contexts. -* **`pci`** - This parameter expects **`ecam`**, **`io`** or **`none`**. When selecting **`none`** - the kernel will not use PCI resources/devices. +- **`pci`** - This parameter expects **`ecam`**, **`io`** or **`none`**. When selecting **`none`** + the kernel will not use PCI resources/devices. -* **`root`** - This parameter configures the device to use as the root file system. It defaults to **`/dev/hda`** if unspecified. +- **`root`** - This parameter configures the device to use as the root file system. It defaults to **`/dev/hda`** if unspecified. -* **`pcspeaker`** - This parameter controls whether the kernel can use the PC speaker or not. It defaults to **`off`** and can be set to **`on`** to enable the PC speaker. +- **`pcspeaker`** - This parameter controls whether the kernel can use the PC speaker or not. It defaults to **`off`** and can be set to **`on`** to enable the PC speaker. -* **`smp`** - This parameter expects a binary value of **`on`** or **`off`**. If enabled kernel will - enable available APs (application processors) and use them with the BSP (Bootstrap processor) to - schedule and run threads. - This parameter defaults to **`off`**. This parameter requires **`enable_ioapic`** to be enabled - and a `MADT` (APIC) table to be available. +- **`smp`** - This parameter expects a binary value of **`on`** or **`off`**. If enabled kernel will + enable available APs (application processors) and use them with the BSP (Bootstrap processor) to + schedule and run threads. + This parameter defaults to **`off`**. This parameter requires **`enable_ioapic`** to be enabled + and a `MADT` (APIC) table to be available. -* **`nvme_poll`** - This parameter configures the NVMe drive to use polling instead of interrupt driven completion. +- **`nvme_poll`** - This parameter configures the NVMe drive to use polling instead of interrupt driven completion. -* **`system_mode`** - This parameter is not interpreted by the Kernel, and is made available at `/sys/kernel/system_mode`. SystemServer uses it to select the set of services that should be started. Common values are: - - **`graphical`** (default) - Boots the system in the normal graphical mode. - - **`self-test`** - Boots the system in self-test, validation mode. - - **`text`** - Boots the system in text only mode. (You may need to also set **`graphics_subsystem_mode=off`**.) +- **`system_mode`** - This parameter is not interpreted by the Kernel, and is made available at `/sys/kernel/system_mode`. SystemServer uses it to select the set of services that should be started. Common values are: -* **`time`** - This parameter expects one of the following values. **`modern`** - This configures the system to attempt - to use High Precision Event Timer (HPET) on boot. **`legacy`** - Configures the system to use the legacy programmable interrupt - time for managing system team. - -* **`vmmouse`** - This parameter expects a binary value of **`on`** or **`off`**. If enabled and - running on a VMWare Hypervisor, the kernel will enable absolute mouse mode. + - **`graphical`** (default) - Boots the system in the normal graphical mode. + - **`self-test`** - Boots the system in self-test, validation mode. + - **`text`** - Boots the system in text only mode. (You may need to also set **`graphics_subsystem_mode=off`**.) -* **`disable_kaslr`** - If present on the command line, the KASLR security mitigation will be disabled. +- **`time`** - This parameter expects one of the following values. **`modern`** - This configures the system to attempt + to use High Precision Event Timer (HPET) on boot. **`legacy`** - Configures the system to use the legacy programmable interrupt + time for managing system team. +- **`vmmouse`** - This parameter expects a binary value of **`on`** or **`off`**. If enabled and + running on a VMWare Hypervisor, the kernel will enable absolute mouse mode. + +- **`disable_kaslr`** - If present on the command line, the KASLR security mitigation will be disabled. ## See also -* [`SystemServer`(7)](help://man/7/SystemServer). +- [`SystemServer`(7)](help://man/7/SystemServer). diff --git a/Base/usr/share/man/man7/proc.md b/Base/usr/share/man/man7/proc.md index 4a100714f9a..03aeecd6353 100644 --- a/Base/usr/share/man/man7/proc.md +++ b/Base/usr/share/man/man7/proc.md @@ -10,16 +10,16 @@ All of the output layout (besides symbolic links) in the ProcFS nodes is JSON. ### Per process entries -* **`cwd`** - a symbolic link to current work directory of a process. -* **`exe`** - a symbolic link to the executable binary of the process. -* **`fds`** - this node exports information on all currently open file descriptors. -* **`fd`** - this directory lists all currently open file descriptors. -* **`perf_events`** - this node exports information being gathered during a profile on a process. -* **`pledge`** - this node exports information on all the pledge requests and promises of a process. -* **`stacks`** - this directory lists all stack traces of process threads. -* **`unveil`** - this node exports information on all the unveil requests of a process. -* **`vm`** - this node exports information on virtual memory mappings of a process. -* **`children`** - this directory lists all the child processes of a process. +- **`cwd`** - a symbolic link to current work directory of a process. +- **`exe`** - a symbolic link to the executable binary of the process. +- **`fds`** - this node exports information on all currently open file descriptors. +- **`fd`** - this directory lists all currently open file descriptors. +- **`perf_events`** - this node exports information being gathered during a profile on a process. +- **`pledge`** - this node exports information on all the pledge requests and promises of a process. +- **`stacks`** - this directory lists all stack traces of process threads. +- **`unveil`** - this node exports information on all the unveil requests of a process. +- **`vm`** - this node exports information on virtual memory mappings of a process. +- **`children`** - this directory lists all the child processes of a process. ### Consistency and stability of data across multiple read operations @@ -33,7 +33,7 @@ reset the offset to 0. ## See also -* [`mount`(2))](help://man/2/mount). -* [`boot_parameters`(7))](help://man/7/boot_parameters). -* [`pledge`(2))](help://man/2/pledge). -* [`unveil`(2))](help://man/2/unveil). +- [`mount`(2))](help://man/2/mount). +- [`boot_parameters`(7))](help://man/7/boot_parameters). +- [`pledge`(2))](help://man/2/pledge). +- [`unveil`(2))](help://man/2/unveil). diff --git a/Base/usr/share/man/man7/setuid_overview.md b/Base/usr/share/man/man7/setuid_overview.md index 413c5b4217c..6dd785ea19b 100644 --- a/Base/usr/share/man/man7/setuid_overview.md +++ b/Base/usr/share/man/man7/setuid_overview.md @@ -8,7 +8,7 @@ Each process runs has a user ID and a group ID. By default, a new process inheri Each file has permissions that control if it can be read, written, and executed by processes belonging to its owner, by processes belonging to other users in the owner's group, and by processes belonging to others. -In addition to the access permissions bits, executables may have the "Set User ID" and the "Set Group ID" bit set. When executables with these bits set are executed, they run with the user or group ID of the executable, instead of with the user and group ID of their parent process. These binaries are also called "SUID binaries" or "setuid binaries" (or "SGID binaries" or "setgid binaries" for the "Set Group ID" bit). +In addition to the access permissions bits, executables may have the "Set User ID" and the "Set Group ID" bit set. When executables with these bits set are executed, they run with the user or group ID of the executable, instead of with the user and group ID of their parent process. These binaries are also called "SUID binaries" or "setuid binaries" (or "SGID binaries" or "setgid binaries" for the "Set Group ID" bit). The motivation behind SUID binaries is that they allow users to do tasks that would normally require elevated permissions, without having to give users these permissions fully. @@ -22,7 +22,7 @@ Since SUID binaries are able to bypass access checks, only carefully selected bi In some instances, it is useful for a SUID binary to either temporarily or permanently drop its permissions and set the effective user ID to the real user ID. -To make this possible, each process has *three* user (and group) IDs: The (real) user ID, the *effective* user ID, and the *saved* user ID. When a process executes a normal binary, all three IDs are set to the parent process's user ID. However, when a process executes a SUID binary, the process runs with the parent process's ID as its real ID, but it takes its effective ID and saved ID from the binary. (Analogously for the group ID for SGID binaries.) +To make this possible, each process has _three_ user (and group) IDs: The (real) user ID, the _effective_ user ID, and the _saved_ user ID. When a process executes a normal binary, all three IDs are set to the parent process's user ID. However, when a process executes a SUID binary, the process runs with the parent process's ID as its real ID, but it takes its effective ID and saved ID from the binary. (Analogously for the group ID for SGID binaries.) The function [`setresuid`(2)](help://man/2/getresuid) can change the real, effective, and saved user ID of a process -- but for non-root processes it is only valid to set each new ID to the current value of real, effective, or saved user ID. Since SUID binaries start with the binary's owner as effective and saved user ID and with the current user's ID as real user ID, this allows switching the effective user ID between the SUID owner's ID and the current user's ID. @@ -56,16 +56,16 @@ if (setresuid(new_uid, new_uid, new_uid) < 0) (On SerenityOS, this is usually the same as calling `setuid(new_uid)`, but easier to reason about.) -Changing group IDs is analogous. Since changing the user ID changes the permissions of a process, group privileges should be dropped before user privileges are dropped, and if they're dropped temporarily, user privileges should be restored before group privileges are restored. +Changing group IDs is analogous. Since changing the user ID changes the permissions of a process, group privileges should be dropped before user privileges are dropped, and if they're dropped temporarily, user privileges should be restored before group privileges are restored. For historical reasons, there are many functions for setting and getting these IDs. `setresuid()`, `setresgid()`, `getresuid()`, and `getresgid()` are the most flexible of these functions and they have the easiest to understand semantics. ## See also -* "Setuid Demystified", Proceedings of the 11th USENIX Security Symposium, August 2002, Pages 171–190 -* [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) -* [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) -* [`getuid`(2) / `getgid`(2)](help://man/2/getuid) -* [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) -* [`setuid`(2) / `setgid`(2)](help://man/2/setuid) -* [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) +- "Setuid Demystified", Proceedings of the 11th USENIX Security Symposium, August 2002, Pages 171–190 +- [`getresuid`(2) / `getresgid`(2)](help://man/2/getresuid) +- [`geteuid`(2) / `getegid`(2)](help://man/2/geteuid) +- [`getuid`(2) / `getgid`(2)](help://man/2/getuid) +- [`seteuid`(2) / `setegid`(2)](help://man/2/seteuid) +- [`setuid`(2) / `setgid`(2)](help://man/2/setuid) +- [`setresuid`(2) / `setresgid`(2)](help://man/2/setresuid) diff --git a/Base/usr/share/man/man7/sys.md b/Base/usr/share/man/man7/sys.md index d4e02b389a1..69129af146c 100644 --- a/Base/usr/share/man/man7/sys.md +++ b/Base/usr/share/man/man7/sys.md @@ -11,10 +11,11 @@ The kernel can expose system (kernel, firmware and hardware) related information This directory include a subdirectory for each discovered and registered bus in the system. Possible busses to be exposed in this directory are: + 1. The `pci` subdirectory that includes all discovered PCI devices as subdirectories. -The subdirectories of the PCI devices include files with basic information on the devices. + The subdirectories of the PCI devices include files with basic information on the devices. 2. The `usb` subdirectory that includes all discovered USB devices as files. -The files of the USB devices export basic information on the devices. + The files of the USB devices export basic information on the devices. ### `dev` directory @@ -40,41 +41,41 @@ and other kernel-related data to userspace. #### `kernel` directory entries -* **`processes`** - This node exports a list of all processes that currently exist. -* **`cpuinfo`** - This node exports information on the CPU. -* **`df`** - This node exports information on mounted filesystems and basic statistics on -them. -* **`dmesg`** - This node exports information from the kernel log. -* **`interrupts`** - This node exports information on all IRQ handlers and basic statistics on -them. -* **`keymap`** - This node exports information on the currently used keymap. -* **`memstat`** - This node exports statistics on memory allocation in the kernel. -* **`profile`** - This node exports statistics on profiling data. -* **`stats`** - This node exports statistics on scheduler timing data. -* **`uptime`** - This node exports the uptime data. -* **`power_state`** - This node only responds to write requests on it. A written value of `1` results -in system reboot. A written value of `2` results in system shutdown. -* **`load_base`** - This node reveals the loading address of the kernel. -* **`system_mode`** - This node exports the chosen system mode as it was decided based on the kernel commandline or a default value. -* **`cmdline`** - This node exports the kernel boot commandline that was passed from the bootloader. -* **`request_panic`** - This node allows userspace to trigger (an artificial) kernel panic by writing/truncating it. +- **`processes`** - This node exports a list of all processes that currently exist. +- **`cpuinfo`** - This node exports information on the CPU. +- **`df`** - This node exports information on mounted filesystems and basic statistics on + them. +- **`dmesg`** - This node exports information from the kernel log. +- **`interrupts`** - This node exports information on all IRQ handlers and basic statistics on + them. +- **`keymap`** - This node exports information on the currently used keymap. +- **`memstat`** - This node exports statistics on memory allocation in the kernel. +- **`profile`** - This node exports statistics on profiling data. +- **`stats`** - This node exports statistics on scheduler timing data. +- **`uptime`** - This node exports the uptime data. +- **`power_state`** - This node only responds to write requests on it. A written value of `1` results + in system reboot. A written value of `2` results in system shutdown. +- **`load_base`** - This node reveals the loading address of the kernel. +- **`system_mode`** - This node exports the chosen system mode as it was decided based on the kernel commandline or a default value. +- **`cmdline`** - This node exports the kernel boot commandline that was passed from the bootloader. +- **`request_panic`** - This node allows userspace to trigger (an artificial) kernel panic by writing/truncating it. #### `net` directory -* **`adapters`** - This node exports information on all currently-discovered network adapters. -* **`arp`** - This node exports information on the kernel ARP table. -* **`local`** - This node exports information on local (Unix) sockets. -* **`tcp`** - This node exports information on TCP sockets. -* **`udp`** - This node exports information on UDP sockets. +- **`adapters`** - This node exports information on all currently-discovered network adapters. +- **`arp`** - This node exports information on the kernel ARP table. +- **`local`** - This node exports information on local (Unix) sockets. +- **`tcp`** - This node exports information on TCP sockets. +- **`udp`** - This node exports information on UDP sockets. #### `conf` directory This subdirectory includes global settings of the kernel. -* **`caps_lock_to_ctrl`** - This node controls remapping of of caps lock to the Ctrl key. -* **`kmalloc_stacks`** - This node controls whether to send information about kmalloc to debug log. -* **`ubsan_is_deadly`** - This node controls the deadliness of the kernel undefined behavior -sanitizer errors. +- **`caps_lock_to_ctrl`** - This node controls remapping of of caps lock to the Ctrl key. +- **`kmalloc_stacks`** - This node controls whether to send information about kmalloc to debug log. +- **`ubsan_is_deadly`** - This node controls the deadliness of the kernel undefined behavior + sanitizer errors. ### Consistency and stability of data across multiple read operations @@ -82,10 +83,10 @@ When opening a data node, the kernel generates the required data so it's prepare for read operation when requested to. However, in order to ensure that multiple reads will not create a corrupted data from that data node, a read operation alone will not inquire the kernel to refresh the data. -To keep data output being refreshed, the userland has to re-open the data node with a +To keep data output being refreshed, the userland has to re-open the data node with a new file descriptor, or to perform the `lseek` syscall on the open file descriptor to reset the offset to 0. ## See also -* [`mount`(2))](help://man/2/mount). +- [`mount`(2))](help://man/2/mount). diff --git a/Base/usr/share/man/man8/EchoServer.md b/Base/usr/share/man/man8/EchoServer.md index 7b945be7afe..e79d9c26802 100644 --- a/Base/usr/share/man/man8/EchoServer.md +++ b/Base/usr/share/man/man8/EchoServer.md @@ -14,7 +14,7 @@ EchoServer is a basic echo server for Serenity. By default, it runs on port 7. ## Options -* `-p`: Choose different port for EchoServer to attach to. +- `-p`: Choose different port for EchoServer to attach to. ## Examples diff --git a/Base/usr/share/man/man8/TelnetServer.md b/Base/usr/share/man/man8/TelnetServer.md index 10c1901236b..bdf20109e6c 100644 --- a/Base/usr/share/man/man8/TelnetServer.md +++ b/Base/usr/share/man/man8/TelnetServer.md @@ -7,6 +7,7 @@ TelnetServer - Serenity telnet server ```sh $ TelnetServer [-p port] [-c command] ``` + ## Description TelnetServer is a basic telnet server for Serenity. By default, it @@ -15,10 +16,10 @@ must be run as root. ## Options -* `--help`: Display help message and exit -* `--version`: Print version -* `-p port`: Port to listen on -* `-c command`: Program to run on connection +- `--help`: Display help message and exit +- `--version`: Print version +- `-p port`: Port to listen on +- `-c command`: Program to run on connection ## Examples diff --git a/Base/usr/share/man/man8/WebServer.md b/Base/usr/share/man/man8/WebServer.md index 571e3a3fd58..823ca535e56 100644 --- a/Base/usr/share/man/man8/WebServer.md +++ b/Base/usr/share/man/man8/WebServer.md @@ -10,15 +10,15 @@ $ WebServer [--listen-address listen_address] [--port port] [--user username] [- ## Options -* `--help`: Display help message and exit -* `--version`: Print version -* `-l listen_address`, `--listen-address listen_address`: IP address to listen on -* `-p port`, `--port port`: Port to listen on -* `-U username`, `--user username`: HTTP basic authentication username -* `-P password`, `--pass password`: HTTP basic authentication password +- `--help`: Display help message and exit +- `--version`: Print version +- `-l listen_address`, `--listen-address listen_address`: IP address to listen on +- `-p port`, `--port port`: Port to listen on +- `-U username`, `--user username`: HTTP basic authentication username +- `-P password`, `--pass password`: HTTP basic authentication password ## Arguments -* `path`: Path to serve the contents of +- `path`: Path to serve the contents of <!-- Auto-generated through ArgsParser --> diff --git a/Base/usr/share/man/man8/blockdev.md b/Base/usr/share/man/man8/blockdev.md index 66134774cb9..f9a25c36eb5 100644 --- a/Base/usr/share/man/man8/blockdev.md +++ b/Base/usr/share/man/man8/blockdev.md @@ -14,8 +14,8 @@ The `blockdev` command call ioctls on the given block device. ## Options -* `-s`, `--size`: Get disk size in bytes -* `-b`, `--block-size`: Get block size in bytes +- `-s`, `--size`: Get disk size in bytes +- `-b`, `--block-size`: Get block size in bytes ## Examples diff --git a/Base/usr/share/man/man8/groupadd.md b/Base/usr/share/man/man8/groupadd.md index 1dffa435957..8630b135c70 100644 --- a/Base/usr/share/man/man8/groupadd.md +++ b/Base/usr/share/man/man8/groupadd.md @@ -16,12 +16,12 @@ This program must be run as root. ## Options -* `-g`, `--gid` _gid_: The group identifier for the new group. If not specified, an unused GID above `100` will be auto-generated. -* `-U`, `--users` user-list: A comma-separated list of usernames to add as members of the new group +- `-g`, `--gid` _gid_: The group identifier for the new group. If not specified, an unused GID above `100` will be auto-generated. +- `-U`, `--users` user-list: A comma-separated list of usernames to add as members of the new group ## Files -* `/etc/group` - new group information (such GID) is appended to this file. +- `/etc/group` - new group information (such GID) is appended to this file. ## Examples @@ -31,6 +31,7 @@ This program must be run as root. ``` ## See Also -* [`useradd`(8)](help://man/8/useradd) -* [`groupdel`(8)](help://man/8/groupdel) -* [`groups`(1)](help://man/1/groups) + +- [`useradd`(8)](help://man/8/useradd) +- [`groupdel`(8)](help://man/8/groupdel) +- [`groups`(1)](help://man/1/groups) diff --git a/Base/usr/share/man/man8/groupdel.md b/Base/usr/share/man/man8/groupdel.md index 5ae3f074e59..892b7db366e 100644 --- a/Base/usr/share/man/man8/groupdel.md +++ b/Base/usr/share/man/man8/groupdel.md @@ -24,14 +24,14 @@ You should manually check all users to ensure that no user remain in this group. ## Exit Values -* 0 - Success -* 1 - Couldn't update the group file -* 6 - Specified group doesn't exist -* 8 - Can't remove user's primary group +- 0 - Success +- 1 - Couldn't update the group file +- 6 - Specified group doesn't exist +- 8 - Can't remove user's primary group ## Files -* `/etc/group` - group information (such as GID) in this file is deleted. +- `/etc/group` - group information (such as GID) in this file is deleted. ## Examples @@ -40,6 +40,7 @@ You should manually check all users to ensure that no user remain in this group. ``` ## See Also -* [`userdel`(8)](help://man/8/userdel) -* [`groupadd`(8)](help://man/8/groupadd) -* [`groups`(1)](help://man/1/groups) + +- [`userdel`(8)](help://man/8/userdel) +- [`groupadd`(8)](help://man/8/groupadd) +- [`groups`(1)](help://man/1/groups) diff --git a/Base/usr/share/man/man8/lsblk.md b/Base/usr/share/man/man8/lsblk.md index 9acf2eda43e..e3de3d193dd 100644 --- a/Base/usr/share/man/man8/lsblk.md +++ b/Base/usr/share/man/man8/lsblk.md @@ -15,7 +15,7 @@ It shows a brief list of these devices. ## Files -* `/sys/devices/storage` - source of the storage devices list. +- `/sys/devices/storage` - source of the storage devices list. ## Examples diff --git a/Base/usr/share/man/man8/lsdev.md b/Base/usr/share/man/man8/lsdev.md index d04758dea23..e065fb15af8 100644 --- a/Base/usr/share/man/man8/lsdev.md +++ b/Base/usr/share/man/man8/lsdev.md @@ -16,8 +16,8 @@ family name per allocation. ## Files -* `/sys/kernel/chardev_major_allocs` - list of the major number allocations for character devices. -* `/sys/kernel/blockdev_major_allocs` - list of the major number allocations for block devices. +- `/sys/kernel/chardev_major_allocs` - list of the major number allocations for character devices. +- `/sys/kernel/blockdev_major_allocs` - list of the major number allocations for block devices. ## Examples diff --git a/Base/usr/share/man/man8/lspci.md b/Base/usr/share/man/man8/lspci.md index 8816b7902b8..59bafb8a650 100644 --- a/Base/usr/share/man/man8/lspci.md +++ b/Base/usr/share/man/man8/lspci.md @@ -15,13 +15,13 @@ and devices connected to them. It shows a brief list of devices. ## Options -* `-n`, `--numerical`: Don't try to resolve numerical PCI IDs. This is useful when -there is a need to see the actual PCI IDs, or if `/res/pci.ids` file is not available. +- `-n`, `--numerical`: Don't try to resolve numerical PCI IDs. This is useful when + there is a need to see the actual PCI IDs, or if `/res/pci.ids` file is not available. ## Files -* `/sys/bus/pci` - source of the PCI devices list. -* `/res/pci.ids` - a database of PCI identifiers used to match available devices to their vendor, device and class names. +- `/sys/bus/pci` - source of the PCI devices list. +- `/res/pci.ids` - a database of PCI identifiers used to match available devices to their vendor, device and class names. ## Examples diff --git a/Base/usr/share/man/man8/mount.md b/Base/usr/share/man/man8/mount.md index b69e1fb385e..cd13d18fbf8 100644 --- a/Base/usr/share/man/man8/mount.md +++ b/Base/usr/share/man/man8/mount.md @@ -27,7 +27,7 @@ fstype defaults to `ext2`). A special source value "none" is recognized, in which case [`mount`(8)](help://man/8/mount) will not attempt to open the source as a file, and will pass an invalid file descriptor to [`mount`(2)](help://man/2/mount). This is -useful for mounting pseudo filesystems. +useful for mounting pseudo filesystems. Options correspond to the mount flags, and should be specified as a comma-separated list of flag names (lowercase and without the `MS_` prefix). @@ -35,9 +35,9 @@ Additionally, the name `defaults` is accepted and ignored. ## Files -* `/etc/fstab` - read by `mount -a` on startup to find out which filesystems to mount. -* `/etc/fstab.d` - directory with drop-in additions to the normal `fstab` file, also read by `mount -a`. -* `/sys/kernel/df` - read by `mount` to get information about mounted filesystems. +- `/etc/fstab` - read by `mount -a` on startup to find out which filesystems to mount. +- `/etc/fstab.d` - directory with drop-in additions to the normal `fstab` file, also read by `mount -a`. +- `/sys/kernel/df` - read by `mount` to get information about mounted filesystems. ## Examples @@ -51,5 +51,5 @@ $ mount /home/anon/myfilesystem.bin /mnt ## See also -* [`mount`(2)](help://man/2/mount) -* [`umount`(8)](help://man/8/umount) +- [`mount`(2)](help://man/2/mount) +- [`umount`(8)](help://man/8/umount) diff --git a/Base/usr/share/man/man8/ping.md b/Base/usr/share/man/man8/ping.md index 34ee2687083..762c7ee5615 100644 --- a/Base/usr/share/man/man8/ping.md +++ b/Base/usr/share/man/man8/ping.md @@ -10,17 +10,17 @@ $ ping [--count count] [-i interval] [-W interval] [--size size] [--quiet] [-t t ## Options -* `--help`: Display help message and exit. -* `--version`: Print version. -* `-c count`, `--count count`: Stop after sending specified number of ECHO_REQUEST packets. -* `-i interval`: Wait `interval` seconds between sending each ECHO_REQUEST packet. Fractional seconds are allowed. Only super-user can set the interval value less than 0.2 seconds. -* `-W interval`: Time in seconds to wait for a reply for each packet sent. Fractional seconds are allowed. 0 means infinite timeout. -* `-s size`, `--size size`: Amount of bytes to send as payload in the ECHO_REQUEST packets. -* `-q`, `--quiet`: Quiet mode. Only display the summary when finished. -* `-t`, `--ttl`: Set the TTL(time-to-live) value of the ICMP packets. -* `-A`, `--adaptive`: Adaptive ping. The interval between each ECHO_REQUEST adapts to the RTT(round-trip-time). -* `-f`, `--flood`: Flood ping. For every ECHO_REQUEST sent a period '.' is printed, while for every ECHO_REPLY received a backspace is printed. This provides a rapid display of how many packets are being dropped. If interval is not given, it sets interval to 0 and outputs packets as fast as they come back. Only super-user may use this option with 0 interval. +- `--help`: Display help message and exit. +- `--version`: Print version. +- `-c count`, `--count count`: Stop after sending specified number of ECHO_REQUEST packets. +- `-i interval`: Wait `interval` seconds between sending each ECHO_REQUEST packet. Fractional seconds are allowed. Only super-user can set the interval value less than 0.2 seconds. +- `-W interval`: Time in seconds to wait for a reply for each packet sent. Fractional seconds are allowed. 0 means infinite timeout. +- `-s size`, `--size size`: Amount of bytes to send as payload in the ECHO_REQUEST packets. +- `-q`, `--quiet`: Quiet mode. Only display the summary when finished. +- `-t`, `--ttl`: Set the TTL(time-to-live) value of the ICMP packets. +- `-A`, `--adaptive`: Adaptive ping. The interval between each ECHO_REQUEST adapts to the RTT(round-trip-time). +- `-f`, `--flood`: Flood ping. For every ECHO_REQUEST sent a period '.' is printed, while for every ECHO_REPLY received a backspace is printed. This provides a rapid display of how many packets are being dropped. If interval is not given, it sets interval to 0 and outputs packets as fast as they come back. Only super-user may use this option with 0 interval. ## Arguments -* `host`: Host to ping +- `host`: Host to ping diff --git a/Base/usr/share/man/man8/pls.md b/Base/usr/share/man/man8/pls.md index 8e8de47dd4a..aa0dd03e89f 100644 --- a/Base/usr/share/man/man8/pls.md +++ b/Base/usr/share/man/man8/pls.md @@ -37,4 +37,5 @@ root ``` ## See also -* [`su`(1)](help://man/1/su) + +- [`su`(1)](help://man/1/su) diff --git a/Base/usr/share/man/man8/purge.md b/Base/usr/share/man/man8/purge.md index b49bb61f239..9c8d1017928 100644 --- a/Base/usr/share/man/man8/purge.md +++ b/Base/usr/share/man/man8/purge.md @@ -15,8 +15,8 @@ be released without interacting with its userspace owner(s). ## Options -* `-c`: Release all clean inode-backed memory. -* `-v`: Release all purgeable memory currently marked volatile. +- `-c`: Release all clean inode-backed memory. +- `-v`: Release all purgeable memory currently marked volatile. If no options are specified, all possible memory is released. diff --git a/Base/usr/share/man/man8/sysctl.md b/Base/usr/share/man/man8/sysctl.md index ebd93019397..acb254015f3 100644 --- a/Base/usr/share/man/man8/sysctl.md +++ b/Base/usr/share/man/man8/sysctl.md @@ -16,17 +16,17 @@ Available parameters are listed under /sys/kernel/conf/. ## Options -* `-a`: Display all kernel parameters and associated values. -* `-w`: Set kernel parameters to the specified values. +- `-a`: Display all kernel parameters and associated values. +- `-w`: Set kernel parameters to the specified values. ## Arguments -* `variable`: Retrieve the specified parameter. -* `variable=value`: Set the specified parameter to the specified value. The option `-w` has to be specified. +- `variable`: Retrieve the specified parameter. +- `variable=value`: Set the specified parameter to the specified value. The option `-w` has to be specified. ## Files -* `/sys/kernel/conf` - source of kernel parameters +- `/sys/kernel/conf` - source of kernel parameters ## Examples diff --git a/Base/usr/share/man/man8/umount.md b/Base/usr/share/man/man8/umount.md index d1c784a6bac..82db2cbb7a8 100644 --- a/Base/usr/share/man/man8/umount.md +++ b/Base/usr/share/man/man8/umount.md @@ -9,7 +9,8 @@ $ umount <mountpoint> ``` ## Arguments -* `mountpoint`: File system path to unmount + +- `mountpoint`: File system path to unmount ## Description @@ -23,4 +24,4 @@ $ umount <mountpoint> ## See also -* [`mount`(8)](help://man/8/mount) +- [`mount`(8)](help://man/8/mount) diff --git a/Base/usr/share/man/man8/useradd.md b/Base/usr/share/man/man8/useradd.md index c24784f260a..d2c9760da54 100644 --- a/Base/usr/share/man/man8/useradd.md +++ b/Base/usr/share/man/man8/useradd.md @@ -18,26 +18,26 @@ This program must be run as root. ## Options -* `-u`, `--uid` _uid_: The user identifier for the new user. If not specified, an unused UID above `1000` will be auto-generated. -* `-g`, `--gid` _group_: The group name or identifier for the new user. If not specified, it will default to 100 (the **users** group). -* `-p`, `--password` _password_: The encrypted password for the new user. If not specified, it will default to blank. -* `-s`, `--shell` _path-to-shell_: The shell binary for this login. The default is `/bin/Shell`. -* `-m`, `--create-home`: Create the specified home directory for this new user. -* `-d`, `--home-dir` _path_: Set the home directory for this user to path. By default, this is `/home/username`, where `username` is the value of login. -* `-n`, `--gecos` _general-info_: GECOS information about this login. See [Wikipedia](https://en.wikipedia.org/wiki/Gecos_field) for more information. +- `-u`, `--uid` _uid_: The user identifier for the new user. If not specified, an unused UID above `1000` will be auto-generated. +- `-g`, `--gid` _group_: The group name or identifier for the new user. If not specified, it will default to 100 (the **users** group). +- `-p`, `--password` _password_: The encrypted password for the new user. If not specified, it will default to blank. +- `-s`, `--shell` _path-to-shell_: The shell binary for this login. The default is `/bin/Shell`. +- `-m`, `--create-home`: Create the specified home directory for this new user. +- `-d`, `--home-dir` _path_: Set the home directory for this user to path. By default, this is `/home/username`, where `username` is the value of login. +- `-n`, `--gecos` _general-info_: GECOS information about this login. See [Wikipedia](https://en.wikipedia.org/wiki/Gecos_field) for more information. ## Exit Values -* 0 - Success -* 1 - Couldn't update the password file -* 3 - Invalid argument to option -* 4 - UID already in use -* 12 - Couldn't create home directory +- 0 - Success +- 1 - Couldn't update the password file +- 3 - Invalid argument to option +- 4 - UID already in use +- 12 - Couldn't create home directory ## Files -* `/etc/passwd` - new user information (such as UID and GID) is appended to this file. -* `/home/` - user home directory is created here if the `-m` flag is specified. +- `/etc/passwd` - new user information (such as UID and GID) is appended to this file. +- `/home/` - user home directory is created here if the `-m` flag is specified. ## Examples @@ -50,5 +50,6 @@ This program must be run as root. ``` ## See also -* [`userdel`(8)](help://man/8/userdel) -* [`usermod`(8)](help://man/8/usermod) + +- [`userdel`(8)](help://man/8/userdel) +- [`usermod`(8)](help://man/8/usermod) diff --git a/Base/usr/share/man/man8/userdel.md b/Base/usr/share/man/man8/userdel.md index 204e1e6720c..1a273cc67e8 100644 --- a/Base/usr/share/man/man8/userdel.md +++ b/Base/usr/share/man/man8/userdel.md @@ -16,19 +16,19 @@ This program must be run as root. ## Options -* `-r`, `--remove`: Remove the home directory for this user if the directory exists. +- `-r`, `--remove`: Remove the home directory for this user if the directory exists. ## Exit Values -* 0 - Success -* 1 - Couldn't update the password file -* 6 - Specified user doesn't exist -* 12 - Couldn't remove home directory +- 0 - Success +- 1 - Couldn't update the password file +- 6 - Specified user doesn't exist +- 12 - Couldn't remove home directory ## Files -* `/etc/passwd` - user information (such as UID and GID) in this file is deleted. -* `/home/` - user home directory is deleted if the `-r` flag is specified. +- `/etc/passwd` - user information (such as UID and GID) in this file is deleted. +- `/home/` - user home directory is deleted if the `-r` flag is specified. ## Examples @@ -39,5 +39,6 @@ This program must be run as root. ``` ## See Also -* [`usermod`(8)](help://man/8/usermod) -* [`useradd`(8)](help://man/8/useradd) + +- [`usermod`(8)](help://man/8/usermod) +- [`useradd`(8)](help://man/8/useradd) diff --git a/Base/usr/share/man/man8/usermod.md b/Base/usr/share/man/man8/usermod.md index 2c98a826268..c9506863f8c 100644 --- a/Base/usr/share/man/man8/usermod.md +++ b/Base/usr/share/man/man8/usermod.md @@ -15,24 +15,25 @@ This program must be run as root. ## Options -* `--help`: Display help message and exit -* `--version`: Print version -* `-a`, `--append`: Append the supplementary groups specified with the -G option to the user -* `-u uid`, `--uid uid`: The new numerical value of the user's ID -* `-g group`, `--gid group`: The group name or number of the user's new initial login group -* `-G groups`, `--groups groups`: Set the user's supplementary groups. Groups are specified with a comma-separated list. Group names or numbers may be used -* `-L`, `--lock`: Lock password -* `-r`, `--remove`: Remove the supplementary groups specified with the -G option from the user -* `-U`, `--unlock`: Unlock password -* `-d new-home`, `--home new-home`: The user's new login directory -* `-m`, `--move`: Move the content of the user's home directory to the new location -* `-s path-to-shell`, `--shell path-to-shell`: The name of the user's new login shell -* `-n general-info`, `--gecos general-info`: Change the GECOS field of the user +- `--help`: Display help message and exit +- `--version`: Print version +- `-a`, `--append`: Append the supplementary groups specified with the -G option to the user +- `-u uid`, `--uid uid`: The new numerical value of the user's ID +- `-g group`, `--gid group`: The group name or number of the user's new initial login group +- `-G groups`, `--groups groups`: Set the user's supplementary groups. Groups are specified with a comma-separated list. Group names or numbers may be used +- `-L`, `--lock`: Lock password +- `-r`, `--remove`: Remove the supplementary groups specified with the -G option from the user +- `-U`, `--unlock`: Unlock password +- `-d new-home`, `--home new-home`: The user's new login directory +- `-m`, `--move`: Move the content of the user's home directory to the new location +- `-s path-to-shell`, `--shell path-to-shell`: The name of the user's new login shell +- `-n general-info`, `--gecos general-info`: Change the GECOS field of the user ## Arguments -* `username`: Username of the account to modify +- `username`: Username of the account to modify ## See also -* [`userdel`(8)](help://man/8/userdel) -* [`useradd`(8)](help://man/8/useradd) + +- [`userdel`(8)](help://man/8/userdel) +- [`useradd`(8)](help://man/8/useradd) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19bbf000f15..52d12823232 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,10 +16,10 @@ Unlike many other software projects, SerenityOS is not concerned with gaining th That said, please do file any bugs you find, keeping the following in mind: -* One issue per bug. Putting multiple things in the same issue makes both discussion and completion unnecessarily complicated. -* No build issues (or other support requests). If the GitHub Actions CI build succeeds, the build problem is most likely on your side. Work it out locally, or ask in the `#build-problems` channel on Discord. -* Don't comment on issues just to add a joke or irrelevant commentary. Hundreds of people get notified about comments so let's keep them relevant. -* For bare metal issues, please include the complete debug log from the serial console and what you tried to do to solve the issue before opening the issue. Don't forget to add the hardware model of your machine and relevant details about it, to help us diagnose what the problem is. +- One issue per bug. Putting multiple things in the same issue makes both discussion and completion unnecessarily complicated. +- No build issues (or other support requests). If the GitHub Actions CI build succeeds, the build problem is most likely on your side. Work it out locally, or ask in the `#build-problems` channel on Discord. +- Don't comment on issues just to add a joke or irrelevant commentary. Hundreds of people get notified about comments so let's keep them relevant. +- For bare metal issues, please include the complete debug log from the serial console and what you tried to do to solve the issue before opening the issue. Don't forget to add the hardware model of your machine and relevant details about it, to help us diagnose what the problem is. ## Human language policy @@ -27,9 +27,9 @@ In SerenityOS, we treat human language as seriously as we do programming languag The following applies to all user-facing strings, code, comments, and commit messages: -* The official project language is American English with ISO 8601 dates and metric units. -* Use proper spelling, grammar, and punctuation. -* Write in an authoritative and technical tone. +- The official project language is American English with ISO 8601 dates and metric units. +- Use proper spelling, grammar, and punctuation. +- Write in an authoritative and technical tone. Everyone is encouraged to make use of tooling (spell checkers, etc) to make this easier. @@ -43,37 +43,37 @@ Nobody is perfect, and sometimes we mess things up. That said, here are some goo **Do:** -* Write in idiomatic SerenityOS C++23, using the `AK` containers in all code. -* Conform to the project coding style found in [CodingStyle.md](https://github.com/SerenityOS/serenity/blob/master/Documentation/CodingStyle.md). Use `clang-format` (version 18 or later) to automatically format C++ files. See [AdvancedBuildInstructions.md](https://github.com/SerenityOS/serenity/blob/master/Documentation/AdvancedBuildInstructions.md#clang-format-updates) for instructions on how to get an up-to-date version if your OS distribution does not ship clang-format-18. -* Choose expressive variable, function and class names. Make it as obvious as possible what the code is doing. -* Split your changes into separate, atomic commits (i.e. A commit per feature or fix, where the build, tests and the system are all functioning). -* Make sure your commits are rebased on the master branch. -* Wrap your commit messages at 72 characters. -* The first line of the commit message is the subject line, and must have the format "Category: Brief description of what's being changed". The category should be the name of a library, application, service, utility, etc. - * Examples: `LibAudio`, `HackStudio`, `Base`, `Kernel`, `ConfigServer`, `cat` - * Don't use a category like "`Userland`" or "`Utilities`", except for generic changes that affect a large portion of code within these directories. - * Don't use specific component names, e.g. C++ class names, as the category either - mention them in the summary instead. E.g. `LibGUI: Brief description of what's being changed in FooWidget` rather than `FooWidget: Brief description of what's being changed` - * Several categories may be combined with `+`, e.g. `LibJS+LibWeb+Browser: ...` -* Write the commit message subject line in the imperative mood ("Foo: Change the way dates work", not "Foo: Changed the way dates work"). -* Write your commit messages in proper English, with care and punctuation. -* Amend your existing commits when adding changes after a review, where relevant. -* Mark each review comment as "resolved" after pushing a fix with the requested changes. -* Add your personal copyright line to files when making substantive changes. (Optional but encouraged!) -* Check the spelling of your code, comments and commit messages. -* If you have images that go along with your code, run `optipng -strip all` on them to optimize and strip away useless metadata - this can reduce file size from multiple kilobytes to a couple hundred bytes. +- Write in idiomatic SerenityOS C++23, using the `AK` containers in all code. +- Conform to the project coding style found in [CodingStyle.md](https://github.com/SerenityOS/serenity/blob/master/Documentation/CodingStyle.md). Use `clang-format` (version 18 or later) to automatically format C++ files. See [AdvancedBuildInstructions.md](https://github.com/SerenityOS/serenity/blob/master/Documentation/AdvancedBuildInstructions.md#clang-format-updates) for instructions on how to get an up-to-date version if your OS distribution does not ship clang-format-18. +- Choose expressive variable, function and class names. Make it as obvious as possible what the code is doing. +- Split your changes into separate, atomic commits (i.e. A commit per feature or fix, where the build, tests and the system are all functioning). +- Make sure your commits are rebased on the master branch. +- Wrap your commit messages at 72 characters. +- The first line of the commit message is the subject line, and must have the format "Category: Brief description of what's being changed". The category should be the name of a library, application, service, utility, etc. + - Examples: `LibAudio`, `HackStudio`, `Base`, `Kernel`, `ConfigServer`, `cat` + - Don't use a category like "`Userland`" or "`Utilities`", except for generic changes that affect a large portion of code within these directories. + - Don't use specific component names, e.g. C++ class names, as the category either - mention them in the summary instead. E.g. `LibGUI: Brief description of what's being changed in FooWidget` rather than `FooWidget: Brief description of what's being changed` + - Several categories may be combined with `+`, e.g. `LibJS+LibWeb+Browser: ...` +- Write the commit message subject line in the imperative mood ("Foo: Change the way dates work", not "Foo: Changed the way dates work"). +- Write your commit messages in proper English, with care and punctuation. +- Amend your existing commits when adding changes after a review, where relevant. +- Mark each review comment as "resolved" after pushing a fix with the requested changes. +- Add your personal copyright line to files when making substantive changes. (Optional but encouraged!) +- Check the spelling of your code, comments and commit messages. +- If you have images that go along with your code, run `optipng -strip all` on them to optimize and strip away useless metadata - this can reduce file size from multiple kilobytes to a couple hundred bytes. **Don't:** -* Submit code that's incompatible with the project licence (2-clause BSD.) -* Touch anything outside the stated scope of the PR. -* Iterate excessively on your design across multiple commits. -* Use weasel-words like "refactor" or "fix" to avoid explaining what's being changed. -* End commit message subject lines with a period. -* Include commented-out code. -* Write in C. (Instead, take advantage of C++'s amenities, and don't limit yourself to the standard C library.) -* Attempt large architectural changes until you are familiar with the system and have worked on it for a while. -* Engage in excessive "feng shui programming" by moving code around without quantifiable benefit. -* Add jokes or other "funny" things to user-facing parts of the system. +- Submit code that's incompatible with the project licence (2-clause BSD.) +- Touch anything outside the stated scope of the PR. +- Iterate excessively on your design across multiple commits. +- Use weasel-words like "refactor" or "fix" to avoid explaining what's being changed. +- End commit message subject lines with a period. +- Include commented-out code. +- Write in C. (Instead, take advantage of C++'s amenities, and don't limit yourself to the standard C library.) +- Attempt large architectural changes until you are familiar with the system and have worked on it for a while. +- Engage in excessive "feng shui programming" by moving code around without quantifiable benefit. +- Add jokes or other "funny" things to user-facing parts of the system. ## Pull Request Q&A @@ -87,17 +87,17 @@ Ping them right away if it's something urgent! If it's less urgent, advertise yo ### Who are the project maintainers? -- [@ADKaster](https://github.com/ADKaster) -- [@alimpfard](https://github.com/alimpfard) -- [@AtkinsSJ](https://github.com/AtkinsSJ) -- [@BertalanD](https://github.com/BertalanD) -- [@GMTA](https://github.com/gmta) -- [@kalenikaliaksandr](https://github.com/kalenikaliaksandr) -- [@Lubrsi](https://github.com/Lubrsi) -- [@nico](https://github.com/nico) -- [@tcl3](https://github.com/tcl3) -- [@timschumi](https://github.com/timschumi) -- [@trflynn89](https://github.com/trflynn89) +- [@ADKaster](https://github.com/ADKaster) +- [@alimpfard](https://github.com/alimpfard) +- [@AtkinsSJ](https://github.com/AtkinsSJ) +- [@BertalanD](https://github.com/BertalanD) +- [@GMTA](https://github.com/gmta) +- [@kalenikaliaksandr](https://github.com/kalenikaliaksandr) +- [@Lubrsi](https://github.com/Lubrsi) +- [@nico](https://github.com/nico) +- [@tcl3](https://github.com/tcl3) +- [@timschumi](https://github.com/timschumi) +- [@trflynn89](https://github.com/trflynn89) Maintainership is by invitation only and does not correlate with any particular metric. @@ -117,14 +117,15 @@ It's definitely better to ask on Discord. Due to the volume of GitHub notificati The repository contains a file called `.pre-commit-config.yaml` that defines several 'commit hooks' that can be run automatically just before and after creating a new commit. These hooks lint your commit message, and the changes it contains to ensure they will pass the automated CI for pull requests. To enable these hooks firstly follow the installation instructions available at https://pre-commit.com/#install and then enable one or both of the following hooks: - - pre-commit hook - Runs Meta/lint-ci.sh and Meta/lint-ports.py to ensure changes to the code will pass linting: - ```console - pre-commit install - ``` - - post-commit hook - Lints the commit message to ensure it will pass the commit linting: - ```console - pre-commit install --hook-type commit-msg - ``` + +- pre-commit hook - Runs Meta/lint-ci.sh and Meta/lint-ports.py to ensure changes to the code will pass linting: + ```console + pre-commit install + ``` +- post-commit hook - Lints the commit message to ensure it will pass the commit linting: + ```console + pre-commit install --hook-type commit-msg + ``` ## On abandoned pull requests @@ -134,7 +135,7 @@ To make this easier, we do appreciate it if folks enable the "Allow edits from m ## On ideologically motivated changes -Serenity's goal is to enable collaboration between as many groups as *reasonably* possible, and we welcome contributions that make the project more accessisble to people. +Serenity's goal is to enable collaboration between as many groups as _reasonably_ possible, and we welcome contributions that make the project more accessisble to people. However, Serenity is intended to be a purely technical exercise, in the sense of it not being meant to invoke any sociopolitical change. We explicitly try to avoid drama or getting involved in "external" culture wars, and can reject changes that we feel to be sensitive. diff --git a/Documentation/AdvancedBuildInstructions.md b/Documentation/AdvancedBuildInstructions.md index 49b5a8fb9d2..0d74a91b8af 100644 --- a/Documentation/AdvancedBuildInstructions.md +++ b/Documentation/AdvancedBuildInstructions.md @@ -20,7 +20,6 @@ EOF cp /somewhere/on/your/system/file.txt mnt/home/anon ``` - This will configure your keymap to German (`de`) instead of US English. See [`Base/res/keymaps/`](../Base/res/keymaps/) for a full list. Note that the `keymap` program itself will also modify the `/etc/Keyboard.ini` config file, but this way the change will persist across image rebuilds. ## Ninja build targets @@ -29,48 +28,49 @@ The `Meta/serenity.sh` script provides an abstraction over the build targets whi following build targets cannot be accessed through the script and have to be used directly by changing the current directory to `Build/x86_64` and then running `ninja <target>`: -- `ninja limine-image`: Builds a disk image (`limine_disk_image`) with Limine -- `ninja grub-image`: Builds a disk image (`grub_disk_image`) with GRUB -- `ninja extlinux-image`: Builds a disk image (`extlinux_disk_image`) with extlinux -- `ninja check-style`: Runs the same linters the CI does to verify project style on changed files -- `ninja install-ports`: Copies the entire ports tree into the installed rootfs for building ports in Serenity -- `ninja lint-shell-scripts`: Checks style of shell scripts in the source tree with shellcheck -- `ninja all_generated`: Builds all generated code. Useful for running analysis tools that can use compile_commands.json without a full system build -- `ninja configure-components`: See the [Component Configuration](#component-configuration) section below. +- `ninja limine-image`: Builds a disk image (`limine_disk_image`) with Limine +- `ninja grub-image`: Builds a disk image (`grub_disk_image`) with GRUB +- `ninja extlinux-image`: Builds a disk image (`extlinux_disk_image`) with extlinux +- `ninja check-style`: Runs the same linters the CI does to verify project style on changed files +- `ninja install-ports`: Copies the entire ports tree into the installed rootfs for building ports in Serenity +- `ninja lint-shell-scripts`: Checks style of shell scripts in the source tree with shellcheck +- `ninja all_generated`: Builds all generated code. Useful for running analysis tools that can use compile_commands.json without a full system build +- `ninja configure-components`: See the [Component Configuration](#component-configuration) section below. ## CMake build options There are some optional features that can be enabled during compilation that are intended to help with specific types of development work or introduce experimental features. Currently, the following build options are available: -- `ENABLE_ADDRESS_SANITIZER` and `ENABLE_KERNEL_ADDRESS_SANITIZER`: builds in runtime checks for memory corruption bugs (like buffer overflows and memory leaks) in Lagom test cases and the kernel, respectively. -- `ENABLE_KERNEL_UNDEFINED_SANITIZER`: builds in runtime checks for detecting undefined behavior in the kernel. -- `ENABLE_KERNEL_COVERAGE_COLLECTION`: enables the KCOV API and kernel coverage collection instrumentation. Only useful for coverage guided kernel fuzzing. -- `ENABLE_USERSPACE_COVERAGE_COLLECTION`: enables coverage collection instrumentation for userspace. Currently only works with a Clang build. -- `ENABLE_MEMORY_SANITIZER`: enables runtime checks for uninitialized memory accesses in Lagom test cases. -- `ENABLE_UNDEFINED_SANITIZER`: builds in runtime checks for [undefined behavior](https://en.wikipedia.org/wiki/Undefined_behavior) (like null pointer dereferences and signed integer overflows) in Lagom and the SerenityOS userland. -- `UNDEFINED_BEHAVIOR_IS_FATAL`: makes all undefined behavior sanitizer errors non-recoverable. This option reduces the performance overhead of `ENABLE_UNDEFINED_SANITIZER`. -- `ENABLE_COMPILER_EXPLORER_BUILD`: Skip building non-library entities in Lagom (this only applies to Lagom). -- `ENABLE_FUZZERS`: builds [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. -- `ENABLE_FUZZERS_LIBFUZZER`: builds Clang libFuzzer-based [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. -- `ENABLE_FUZZERS_OSSFUZZ`: builds OSS-Fuzz compatible [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. -- `ENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS`: sets -Og and -ggdb3 compile options for building the Kernel. Allows for easier debugging of Kernel code. By default, the Kernel is built with -O2 instead. -- `ENABLE_ALL_THE_DEBUG_MACROS`: used for checking whether debug code compiles on CI. This should not be set normally, as it clutters the console output and makes the system run very slowly. Instead, enable only the needed debug macros, as described below. -- `ENABLE_ALL_DEBUG_FACILITIES`: used for checking whether debug code compiles on CI. Enables both `ENABLE_ALL_THE_DEBUG_MACROS` and `ENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS`. -- `ENABLE_COMPILETIME_FORMAT_CHECK`: checks for the validity of `std::format`-style format string during compilation. Enabled by default. -- `ENABLE_PCI_IDS_DOWNLOAD`: downloads the [`pci.ids` database](https://pci-ids.ucw.cz/) that contains information about PCI devices at build time, if not already present. Enabled by default. -- `BUILD_LAGOM`: builds [Lagom](../Meta/Lagom/ReadMe.md), which makes various SerenityOS libraries and programs available on the host system. -- `ENABLE_KERNEL_LTO`: builds the kernel with link-time optimization. -- `ENABLE_MOLD_LINKER`: builds the userland with the [`mold` linker](https://github.com/rui314/mold). `mold` can be built by running `Toolchain/BuildMold.sh`. -- `ENABLE_JAKT`: builds the `jakt` compiler as a Lagom host tool and enables building applications and libraries that are written in the jakt language. -- `JAKT_SOURCE_DIR`: `jakt` developer's local checkout of the jakt programming language for rapid testing. To use a local checkout, set to an absolute path when changing the CMake cache of Lagom. e.g. ``cmake -S Meta/Lagom -B Build/lagom -DENABLE_JAKT=ON -DJAKT_SOURCE_DIR=/home/me/jakt`` -- `INCLUDE_WASM_SPEC_TESTS`: downloads and includes the WebAssembly spec testsuite tests. In order to use this option, you will need to install `prettier` and `wabt`. wabt version 1.0.35 or higher is required to pre-process the WebAssembly spec testsuite. -- `INCLUDE_FLAC_SPEC_TESTS`: downloads and includes the xiph.org FLAC test suite. -- `SERENITY_TOOLCHAIN`: Specifies whether to use the established GNU toolchain, or the experimental Clang-based toolchain for building SerenityOS. See the [Clang-based toolchain](#clang-based-toolchain) section below. -- `SERENITY_ARCH`: Specifies which architecture to build for. Currently supported options are `x86_64`, `aarch64`, `riscv64`. -- `BUILD_<component>`: builds the specified component, e.g. `BUILD_HEARTS` (note: must be all caps). Check the components.ini file in your build directory for a list of available components. Make sure to run `ninja clean` and `rm -rf Build/x86_64/Root` after disabling components. These options can be easily configured by using the `ConfigureComponents` utility. See the [Component Configuration](#component-configuration) section below. -- `BUILD_EVERYTHING`: builds all optional components, overrides other `BUILD_<component>` flags when enabled -- `SERENITY_CACHE_DIR`: sets the location of a shared cache of downloaded files. Should not need to be set unless managing a distribution package. -- `ENABLE_NETWORK_DOWNLOADS`: allows downloading files from the internet during the build. Default on, turning off enables offline builds. For offline builds, the structure of the SERENITY_CACHE_DIR must be set up the way that the build expects. -- `ENABLE_ACCELERATED_GRAPHICS`: builds features that use accelerated graphics APIs to speed up painting and drawing using native graphics libraries. + +- `ENABLE_ADDRESS_SANITIZER` and `ENABLE_KERNEL_ADDRESS_SANITIZER`: builds in runtime checks for memory corruption bugs (like buffer overflows and memory leaks) in Lagom test cases and the kernel, respectively. +- `ENABLE_KERNEL_UNDEFINED_SANITIZER`: builds in runtime checks for detecting undefined behavior in the kernel. +- `ENABLE_KERNEL_COVERAGE_COLLECTION`: enables the KCOV API and kernel coverage collection instrumentation. Only useful for coverage guided kernel fuzzing. +- `ENABLE_USERSPACE_COVERAGE_COLLECTION`: enables coverage collection instrumentation for userspace. Currently only works with a Clang build. +- `ENABLE_MEMORY_SANITIZER`: enables runtime checks for uninitialized memory accesses in Lagom test cases. +- `ENABLE_UNDEFINED_SANITIZER`: builds in runtime checks for [undefined behavior](https://en.wikipedia.org/wiki/Undefined_behavior) (like null pointer dereferences and signed integer overflows) in Lagom and the SerenityOS userland. +- `UNDEFINED_BEHAVIOR_IS_FATAL`: makes all undefined behavior sanitizer errors non-recoverable. This option reduces the performance overhead of `ENABLE_UNDEFINED_SANITIZER`. +- `ENABLE_COMPILER_EXPLORER_BUILD`: Skip building non-library entities in Lagom (this only applies to Lagom). +- `ENABLE_FUZZERS`: builds [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. +- `ENABLE_FUZZERS_LIBFUZZER`: builds Clang libFuzzer-based [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. +- `ENABLE_FUZZERS_OSSFUZZ`: builds OSS-Fuzz compatible [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. +- `ENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS`: sets -Og and -ggdb3 compile options for building the Kernel. Allows for easier debugging of Kernel code. By default, the Kernel is built with -O2 instead. +- `ENABLE_ALL_THE_DEBUG_MACROS`: used for checking whether debug code compiles on CI. This should not be set normally, as it clutters the console output and makes the system run very slowly. Instead, enable only the needed debug macros, as described below. +- `ENABLE_ALL_DEBUG_FACILITIES`: used for checking whether debug code compiles on CI. Enables both `ENABLE_ALL_THE_DEBUG_MACROS` and `ENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS`. +- `ENABLE_COMPILETIME_FORMAT_CHECK`: checks for the validity of `std::format`-style format string during compilation. Enabled by default. +- `ENABLE_PCI_IDS_DOWNLOAD`: downloads the [`pci.ids` database](https://pci-ids.ucw.cz/) that contains information about PCI devices at build time, if not already present. Enabled by default. +- `BUILD_LAGOM`: builds [Lagom](../Meta/Lagom/ReadMe.md), which makes various SerenityOS libraries and programs available on the host system. +- `ENABLE_KERNEL_LTO`: builds the kernel with link-time optimization. +- `ENABLE_MOLD_LINKER`: builds the userland with the [`mold` linker](https://github.com/rui314/mold). `mold` can be built by running `Toolchain/BuildMold.sh`. +- `ENABLE_JAKT`: builds the `jakt` compiler as a Lagom host tool and enables building applications and libraries that are written in the jakt language. +- `JAKT_SOURCE_DIR`: `jakt` developer's local checkout of the jakt programming language for rapid testing. To use a local checkout, set to an absolute path when changing the CMake cache of Lagom. e.g. `cmake -S Meta/Lagom -B Build/lagom -DENABLE_JAKT=ON -DJAKT_SOURCE_DIR=/home/me/jakt` +- `INCLUDE_WASM_SPEC_TESTS`: downloads and includes the WebAssembly spec testsuite tests. In order to use this option, you will need to install `prettier` and `wabt`. wabt version 1.0.35 or higher is required to pre-process the WebAssembly spec testsuite. +- `INCLUDE_FLAC_SPEC_TESTS`: downloads and includes the xiph.org FLAC test suite. +- `SERENITY_TOOLCHAIN`: Specifies whether to use the established GNU toolchain, or the experimental Clang-based toolchain for building SerenityOS. See the [Clang-based toolchain](#clang-based-toolchain) section below. +- `SERENITY_ARCH`: Specifies which architecture to build for. Currently supported options are `x86_64`, `aarch64`, `riscv64`. +- `BUILD_<component>`: builds the specified component, e.g. `BUILD_HEARTS` (note: must be all caps). Check the components.ini file in your build directory for a list of available components. Make sure to run `ninja clean` and `rm -rf Build/x86_64/Root` after disabling components. These options can be easily configured by using the `ConfigureComponents` utility. See the [Component Configuration](#component-configuration) section below. +- `BUILD_EVERYTHING`: builds all optional components, overrides other `BUILD_<component>` flags when enabled +- `SERENITY_CACHE_DIR`: sets the location of a shared cache of downloaded files. Should not need to be set unless managing a distribution package. +- `ENABLE_NETWORK_DOWNLOADS`: allows downloading files from the internet during the build. Default on, turning off enables offline builds. For offline builds, the structure of the SERENITY_CACHE_DIR must be set up the way that the build expects. +- `ENABLE_ACCELERATED_GRAPHICS`: builds features that use accelerated graphics APIs to speed up painting and drawing using native graphics libraries. Many parts of the SerenityOS codebase have debug functionality, mostly consisting of additional messages printed to the debug console. This is done via the `<component_name>_DEBUG` macros, which can be enabled individually at build time. They are listed in [this file](../Meta/CMake/all_the_debug_macros.cmake). @@ -81,9 +81,10 @@ To toggle or change a build option, see the [CMake Cache Manipulation](#cmake-ca CMake caches variables and options in the binary directory. This allows a developer to tailor variables that are `set()` within the persistent configuration cache. There are three main ways to manipulate the cache: -- `cmake path/to/binary/dir -DVAR_NAME=Value` -- `ccmake` (TUI interface) -- `cmake-gui` + +- `cmake path/to/binary/dir -DVAR_NAME=Value` +- `ccmake` (TUI interface) +- `cmake-gui` Options can be set via the initial `cmake` invocation that creates the binary directory to set the initial cache for the binary directory. Once the binary directory exists, any of the three options above can be used to change the value of cache variables. @@ -170,6 +171,7 @@ $ ninja -C Build/lagom install For selecting which components of the system to build and install, a helper program, `ConfigureComponents` is available. It requires `whiptail` as a dependency, which is available on most systems in the `newt` or `libnewt` package. To build and run it, run the following commands from the `Build/x86_64` directory: + ```console $ ninja configure-components ``` @@ -210,7 +212,7 @@ To build the Clang-based toolchain, run `BuildClang.sh` from the `Toolchain` dir toolchain that is capable of building applications for the build host and serenity. **Warning:** While the build script is running, your computer may slow down extremely or even lock up for short -intervals. This generally happens if you have more CPU cores than free RAM in gigabytes. To fix this, limit the number +intervals. This generally happens if you have more CPU cores than free RAM in gigabytes. To fix this, limit the number of parallel compile tasks be setting the `MAKEJOBS` environment variable to a number less than your CPU core count. Once the build script finishes, you can use it to compile SerenityOS. Either set the `SERENITY_TOOLCHAIN` build @@ -220,16 +222,16 @@ option to `Clang` as shown [above](#cmake-build-options), or pass `Clang` as the ### Serenity-aware clang tools Building the clang-based toolchain also builds libTooling-based tools such as clang-format, clang-tidy and (optionally) -clangd that are aware of SerenityOS as a valid target. These tools will be installed into ``Toolchain/Local/clang/bin`` by -the script. Pointing your editor's plugins to the custom-built clang tools and a ``compile_commands.json`` from a clang build +clangd that are aware of SerenityOS as a valid target. These tools will be installed into `Toolchain/Local/clang/bin` by +the script. Pointing your editor's plugins to the custom-built clang tools and a `compile_commands.json` from a clang build of Serenity can enable richer error reporting than the tools that are installed for the build host. -To enable building clangd as part of the clang toolchain, set ``CLANG_ENABLE_CLANGD`` environment variable to ``ON``, then run ``Toolchain/BuildClang.sh``. +To enable building clangd as part of the clang toolchain, set `CLANG_ENABLE_CLANGD` environment variable to `ON`, then run `Toolchain/BuildClang.sh`. ## Clang-format updates Some OS distributions don't ship bleeding-edge clang-format binaries. Below are 3 options to acquire an updated clang-format tool, in order of preference: -1) If you have a Debian-based (apt-based) distribution, use the [LLVM apt repositories](https://apt.llvm.org) to install the latest release of clang-format. -2) Compile the SerenityOS-patched LLVM from source using ``Toolchain/BuildClang.sh`` as described above and use the compiled ``Toolchain/Local/clang/bin/clang-format`` binary in your editor and terminal. The meta-lint-ci pre-commit hook will automatically pick up the Toolchain clang-format binary. -3) Compile LLVM from source as described in the LLVM documentation [here](https://llvm.org/docs/GettingStarted.html#compiling-the-llvm-suite-source-code). +1. If you have a Debian-based (apt-based) distribution, use the [LLVM apt repositories](https://apt.llvm.org) to install the latest release of clang-format. +2. Compile the SerenityOS-patched LLVM from source using `Toolchain/BuildClang.sh` as described above and use the compiled `Toolchain/Local/clang/bin/clang-format` binary in your editor and terminal. The meta-lint-ci pre-commit hook will automatically pick up the Toolchain clang-format binary. +3. Compile LLVM from source as described in the LLVM documentation [here](https://llvm.org/docs/GettingStarted.html#compiling-the-llvm-suite-source-code). diff --git a/Documentation/AsynchronousDesign.md b/Documentation/AsynchronousDesign.md index f8ad7b60fc2..a1c3a323521 100644 --- a/Documentation/AsynchronousDesign.md +++ b/Documentation/AsynchronousDesign.md @@ -7,6 +7,7 @@ When working with AsyncResource, the only thing you should pay attention to is not leaving the resource open when you are done with it. This is important both for consistency and for not signaling spurious end-of-data errors to the other party. This close/reset hygiene is not hard to achieve in practice: every AsyncResource is automatically reset during destruction and some resources reset on any error returned by any of their interfaces. The above means that the following snippet is correct: + ```cpp Coroutine<ErrorOr<void>> do_very_meaningful_work() { @@ -19,9 +20,11 @@ Coroutine<ErrorOr<void>> do_very_meaningful_work() CO_TRY(co_await socket.close()); } ``` + and will send a TCP RST if any of the functions (including `process_object`) fails and will close the socket gracefully if everything goes well. Of course, automatic-reset-on-destruction does not always get rid of explicit resets. If asynchronous resource is not local to a fallible function, you will have to call reset manually in case of errors, i. e. + ```cpp Coroutine<ErrorOr<void>> do_very_meaningful_work_second_time(AsyncStream& stream) { @@ -35,7 +38,7 @@ Coroutine<ErrorOr<void>> do_very_meaningful_work_second_time(AsyncStream& stream } ``` -It might be tempting to just do nothing with a stream in this situation. However, this will leave the stream in an unknown state if the function fails, which would necessitate `stream->is_open()` checks later on in the caller (because doing pretty much anything with a closed stream asserts). +It might be tempting to just do nothing with a stream in this situation. However, this will leave the stream in an unknown state if the function fails, which would necessitate `stream->is_open()` checks later on in the caller (because doing pretty much anything with a closed stream asserts). As mentioned in the previous paragraph, in addition to `close` and `reset` methods, resources have an `is_open` method which checks if the resource has already been closed or reset (either explicitly or implicitly by a failed method). `is_open` state cannot change by itself with time (i. e. if a server sends RST when nobody is listening the socket)—one has to call a method on a resource for `open` state to change. @@ -48,6 +51,7 @@ Every AsyncInputStream is effectively buffered by design. This means that all in Typical workflow with AsyncInputStream consists of a number of peeks (until the caller finds what they are looking for in the stream) followed by a read that removes just-peeked object from the buffer. The following example reads an object of an unknown size from the stream: + ```cpp Coroutine<ErrorOr<VeryImportantObject>> read_some_very_important_object(AsyncInputStream& stream) { @@ -88,6 +92,7 @@ If your use-case doesn't require the knowledge of EOF location (i. e. you know h For the EOF-aware applications, AsyncInputStream provides `peek_or_eof`. In contrast to `peek`, `peek_or_eof` returns an additional flag indicating if EOF has been reached. Note that the EOF detection is similar to POSIX streams: first, `peek_or_eof` returns data up to EOF without `is_eof` flag being set, and then, on the next call, it returns the same data with `is_eof` flag set. As an example, let us abuse the said functionality of `peek_or_eof` to implement a completely reliable `is_eof` for an asynchronous stream: + ```cpp Coroutine<ErrorOr<bool>> accurate_is_eof(AsyncInputStream& stream) { auto [_, is_eof] = CO_TRY(co_await stream.peek_or_eof()); @@ -99,6 +104,7 @@ Coroutine<ErrorOr<bool>> accurate_is_eof(AsyncInputStream& stream) { You might notice a seemingly useless read of 0 bytes here. Why do we need it? Well, let us remove it and consider the case when we have a stream with an empty buffer and a single byte left overall. `peek_or_eof` will return that byte without `is_eof` flag set, so `accurate_is_eof` returns false. Next, someone tries to peek that byte with a plain `peek` that will in turn call `peek_or_eof`, which now _will_ set the `is_eof` flag. The flag will then be checked by `peek` and the stream will error out with EIO. Therefore, + > [!IMPORTANT] > If you peek something from a stream, you should read it. diff --git a/Documentation/BareMetalInstallation.md b/Documentation/BareMetalInstallation.md index 4086e1cffa4..0fdae4f2d31 100644 --- a/Documentation/BareMetalInstallation.md +++ b/Documentation/BareMetalInstallation.md @@ -4,7 +4,6 @@ Whilst it is possible to run Serenity on physical x86-compatible hardware, it is not yet ready to be used by non-technical users who aren't prepared to report bugs or assist with its development. For this reason, there are currently no pre-built install images so a bare-metal installation requires that you build an installation image from source. Current hardware support is extremely limited. Most successful hard disk installations have been on Pentium 4 era hardware but by network booting Serenity (which is no longer supported) users have been able to get it running on more modern hardware such as Core i5 machines. - ## Hardware support and requirements Storage-wise Serenity requires a >= 2 GB parallel ATA or SATA disk for IDE/AHCI. Some older SATA chipsets already operate in IDE mode whilst some newer ones will depend upon adjusting a BIOS option to run your SATA controller in IDE (sometimes referred to as Legacy or PATA) mode. SATA AHCI is supported, but may not work on every controller due to bugs in the implementation. @@ -53,7 +52,7 @@ If it happens to you that the system hangs, you should be able to see the last m an assertion or kernel panic. Depending on your hardware setup, the framebuffer could be 80x25 VGA text mode, or high resolution framebuffer with 8x8 font glyphs. -You can force capable multiboot bootloaders to boot Serenity into high resolution mode by editing **Kernel/Arch/i386/Boot/boot.S** and +You can force capable multiboot bootloaders to boot Serenity into high resolution mode by editing **Kernel/Arch/i386/Boot/boot.S** and adding **| MULTIBOOT_VIDEO_MODE** to the end of the **multiboot_flags** before building Serenity. Setting a boot argument of `graphics_subsystem_mode=limited` will force the kernel to not initialize any framebuffer devices, hence allowing the system to boot into console-only mode as `SystemServer` will detect this condition and will not initialize `WindowServer`. diff --git a/Documentation/Browser/AddNewIDLFile.md b/Documentation/Browser/AddNewIDLFile.md index 512a3f5194e..bd531768710 100644 --- a/Documentation/Browser/AddNewIDLFile.md +++ b/Documentation/Browser/AddNewIDLFile.md @@ -5,6 +5,7 @@ Serenity's build system does a lot of work of turning the IDL from a Web spec in For the sake of example, let's say you're wanting to add the `HTMLDetailsElement`. 1. Create `LibWeb/HTML/HTMLDetailsElement.idl` with the contents of the IDL section of the spec. In this case, that would be: + ```webidl [Exposed=Window] interface HTMLDetailsElement : HTMLElement { @@ -15,6 +16,7 @@ interface HTMLDetailsElement : HTMLElement { ``` 2. If the IDL refers to other IDL types, you need to import those. For example, `CSSRule` has an attribute that returns a `CSSStyleSheet`, so that needs to be imported: + ```webidl #import <CSS/CSSStyleSheet.idl> @@ -26,6 +28,7 @@ interface CSSRule { 3. Add a `libweb_js_bindings(HTML/HTMLDetailsElement)` call to [`LibWeb/idl_files.cmake`](../../Userland/Libraries/LibWeb/idl_files.cmake) 4. Forward declare the generated class in [`LibWeb/Forward.h`](../../Userland/Libraries/LibWeb/Forward.h): + - `HTMLDetailsElement` in its namespace. 5. If your type isn't an Event or Element, you will need to add it to [`is_platform_object()`](../../Meta/Lagom/Tools/CodeGenerators/LibWeb/BindingsGenerator/IDLGenerators.cpp) diff --git a/Documentation/Browser/BrowsingContextsAndNavigables.md b/Documentation/Browser/BrowsingContextsAndNavigables.md index 66199c7d4ad..849c6a80138 100644 --- a/Documentation/Browser/BrowsingContextsAndNavigables.md +++ b/Documentation/Browser/BrowsingContextsAndNavigables.md @@ -6,19 +6,19 @@ Before we can dive into how LibWeb and Ladybird implement the HTML web page navigation operations, we need to dive into some fundamental specification concepts. Starting with, how does code actually -execute in a (possibly virtual) machine? Next we'll look at what that means for the ECMAScript +execute in a (possibly virtual) machine? Next we'll look at what that means for the ECMAScript Specification (JavaScript), and finally how the ECMAScript code execution model ties into the -HTML specification to model how to display web content into a browser tab. +HTML specification to model how to display web content into a browser tab. ### Native Code Execution: A Primer When modeling the execution of a native program written in a popular systems language like -C, C++, or Rust, most systems programmers should be familiar with the concepts of *threads* -and *processes*. In a "hosted" environment, the execution of one's userspace program generally +C, C++, or Rust, most systems programmers should be familiar with the concepts of _threads_ +and _processes_. In a "hosted" environment, the execution of one's userspace program generally starts with an underlying operating system creating a process for the application to run in. This process will contain a memory space for program data and code to live in, and an initial, or main thread to start execution on. In order for the operating system to change which -thread is executing on a particular CPU core, it needs to save and restore the *Execution Context* +thread is executing on a particular CPU core, it needs to save and restore the _Execution Context_ for that thread. The Execution Context for a native thread generally consists of a set of CPU registers, any floating point state, a program counter that tracks which instruction should be loaded next, and a stack pointer that points to the local data the thread was using to track @@ -34,10 +34,10 @@ symbol table contained within the object file format. Normally local variable an names and locations are lost in the compile+link steps, but the compiler can be configured to emit extra debug information to allow debuggers to access and modify them at runtime. In order to support something like the dynamic imports of interpreted languages, the programmer has to -call a platform-specific function to load the new module (e.g. ``dlopen`` or ``LoadLibrary``). +call a platform-specific function to load the new module (e.g. `dlopen` or `LoadLibrary`). But after the module is opened, in order to actually refer to any exported symbols from that module the programmer has to retrieve the address of each symbol through another platform specific function -(e.g. ``dlsym`` or ``GetProcAddress``), once per symbol. +(e.g. `dlsym` or `GetProcAddress`), once per symbol. ### ECMAScript Execution Model: Realms and Agents @@ -45,35 +45,35 @@ The ECMAScript specification has analogs for almost all of these concepts in the [Executable Code and Execution Contexts](https://tc39.es/ecma262/#sec-executable-code-and-execution-contexts). Working in the other direction from the native code explanation, ECMAScript describes the accessibility -and scopes of functions, variables, and arguments in terms of [*Environment Records*](https://tc39.es/ecma262/#sec-environment-records). +and scopes of functions, variables, and arguments in terms of [_Environment Records_](https://tc39.es/ecma262/#sec-environment-records). Note that these Environment Records are not actually visible to executing code, and are simply a mechanism -used by the specification authors to model the language. Every function and module has a type +used by the specification authors to model the language. Every function and module has a type of Environment Record that contains the variables, functions, catch clause bindings, and other language constructs that affect which names are visible at any location in the code. These Environment Records are nested, in a tree-like structure that somewhat matches the Abstract Syntax Tree (AST). The root of the tree of Environment Records is the Global Environment Record, which corresponds to the -Global Object and its properties. In JavaScript, there is always a ``this`` value representing the current +Global Object and its properties. In JavaScript, there is always a `this` value representing the current object context. At global scope, the Global Object normally takes that responsibility. In a REPL, that might be some REPL specific global object that has global functions to call for doing things like loading from the filesystem, or even be as complex as Node or Bun. In a Browser context, the Global object is -normally the Window, unless there's a Worker involved. For historical reasons the global ``this`` binding for +normally the Window, unless there's a Worker involved. For historical reasons the global `this` binding for Window contexts is actually a WindowProxy that wraps the Window. This concept is quite different from a native executable, where there's no actual object representing the global scope, simply symbols that the linker and loader make available to each module. While the Global Object and its Global Environment represent the root of the tree of identifiers visible to the executing JavaScript code, the Global Object isn't sufficient to model all the state around -a conceptual thread of execution in ECMAScript. This is where the two concepts of [*Realms*](https://tc39.es/ecma262/#sec-code-realms) -and [*Execution Contexts*](https://tc39.es/ecma262/#sec-execution-contexts) come into play. -A [*Realm Record*](https://tc39.es/ecma262/#realm-record) is a container that holds a global object, -its associated Global Environment, a set of intrinsic objects, and any *host* (also called an *embedder* +a conceptual thread of execution in ECMAScript. This is where the two concepts of [_Realms_](https://tc39.es/ecma262/#sec-code-realms) +and [_Execution Contexts_](https://tc39.es/ecma262/#sec-execution-contexts) come into play. +A [_Realm Record_](https://tc39.es/ecma262/#realm-record) is a container that holds a global object, +its associated Global Environment, a set of intrinsic objects, and any _host_ (also called an _embedder_ in some specification documents) defined extra state that needs to be associated with the realm. In LibWeb, the Host Defined slot holds an object that has the HTML Environment Settings Object for each realm, as well as all the prototypes, constructors, and namespaces that need to be exposed on the Global Object for Web APIs. On top of the Realm abstraction, ECMAScript uses the Execution Context to model the state -of execution of one particular script or module. Each Execution Context belongs to an [*execution context stack*](https://tc39.es/ecma262/#execution-context-stack) -with the topmost context named the [*running execution context*](https://tc39.es/ecma262/#running-execution-context). +of execution of one particular script or module. Each Execution Context belongs to an [_execution context stack_](https://tc39.es/ecma262/#execution-context-stack) +with the topmost context named the [_running execution context_](https://tc39.es/ecma262/#running-execution-context). An Execution Context has information about the current function, the script or module that the current code block belongs to, additional Environment Records required to access names in the current scope, any running generator state, and most importantly to the thread analogy, the state needed to suspend and resume execution of that script. @@ -84,17 +84,17 @@ are actually scheduled to run by the ECMAScript implementation. In the most comm mapping the ECMAScript model to the earlier native concepts of threads and processes in a way that allows for flexibility in the implementation strategies. The last thing that the specification authors want to do is constrain implementations so much that innovation and experimentation becomes impossible. -The method for this mapping is the two related specification mechanisms [*Agents*](https://tc39.es/ecma262/#sec-agents) -and [*Agent Clusters*](https://tc39.es/ecma262/#sec-agent-clusters). The Execution Context stack mentioned +The method for this mapping is the two related specification mechanisms [_Agents_](https://tc39.es/ecma262/#sec-agents) +and [_Agent Clusters_](https://tc39.es/ecma262/#sec-agent-clusters). The Execution Context stack mentioned above actually belongs to an Agent, which holds said stack, a set of metadata about the memory model, -and a shared reference to an [*executing thread*](https://tc39.es/ecma262/#executing-thread). +and a shared reference to an [_executing thread_](https://tc39.es/ecma262/#executing-thread). According to ECMAScript, there should always be at least one Execution Context on the stack, to allow concepts -such as the running execution context to always refer to the topmost Execution Context of the [*surrounding agent*](https://tc39.es/ecma262/#surrounding-agent). +such as the running execution context to always refer to the topmost Execution Context of the [_surrounding agent_](https://tc39.es/ecma262/#surrounding-agent). However, the HTML specification opts to remove the default execution context from the execution context stack at creation, and instead manually pushes and pops execution contexts for script, module, and callback execution. The relationship between Realms and Agents is not 1-1, but N-1. In the ECMAScript specification, this manifests -as a part of the [*Shadow Realm proposal*](https://tc39.es/proposal-shadowrealm/), while the Web platform -requires multiple Realms per Agent to specify the historical behavior of ``<iframe>`` and related elements. +as a part of the [_Shadow Realm proposal_](https://tc39.es/proposal-shadowrealm/), while the Web platform +requires multiple Realms per Agent to specify the historical behavior of `<iframe>` and related elements. An Agent holds a stack of Execution Contexts, with the topmost entry being the running execution context. Each Execution Context holds a Realm and a specific script's context, including the current function and @@ -140,17 +140,15 @@ TODO: Finish this section ## HTML Navigation: Juggling Origins - - ### Global Scopes, Browsing Contexts, Browsing Context Groups, Navigables, and Traversable Navigables TODO: -- Agents defined by the HTML Spec -- Global Objects (Global Scopes) defined by the HTML Spec -- Agents and Browsing Context Groups -- Navigables and their relationship to Browsing Contexts -- Walk through construction of a browser tab, its traversable navigable, and its navigation both same and - cross-origin -- Walk through construction of a browser tab with a nested browsing context and what happens when the - nested context within its navigable container navigates on its own +- Agents defined by the HTML Spec +- Global Objects (Global Scopes) defined by the HTML Spec +- Agents and Browsing Context Groups +- Navigables and their relationship to Browsing Contexts +- Walk through construction of a browser tab, its traversable navigable, and its navigation both same and + cross-origin +- Walk through construction of a browser tab with a nested browsing context and what happens when the + nested context within its navigable container navigates on its own diff --git a/Documentation/Browser/CSSGeneratedFiles.md b/Documentation/Browser/CSSGeneratedFiles.md index e92e7348a94..14ef92bb584 100644 --- a/Documentation/Browser/CSSGeneratedFiles.md +++ b/Documentation/Browser/CSSGeneratedFiles.md @@ -18,7 +18,7 @@ The file is organized as a single JSON object, with keys being property names, a Each property will have some set of these fields on it: | Field | Required | Default | Description | Generated functions | -|----------------------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| +| -------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `affects-layout` | No | `true` | Boolean. Whether changing this property will invalidate the element's layout. | `bool property_affects_layout(PropertyID)` | | `affects-stacking-context` | No | `false` | Boolean. Whether this property can cause a new stacking context for the element. | `bool property_affects_stacking_context(PropertyID)` | | `animation-type` | Yes | | String. How the property should be animated. Defined by the spec. See below. | `AnimationType animation_type_from_longhand_property(PropertyID)` | @@ -37,7 +37,7 @@ Each property will have some set of these fields on it: The [Web Animations spec](https://www.w3.org/TR/web-animations/#animation-type) defines the valid values here: | Spec term | JSON value | -|-------------------|---------------------| +| ----------------- | ------------------- | | not animatable | `none` | | discrete | `discrete` | | by computed value | `by-computed-value` | @@ -49,7 +49,7 @@ The [Web Animations spec](https://www.w3.org/TR/web-animations/#animation-type) The [Quirks spec](https://quirks.spec.whatwg.org/#css) defines these. | Spec term | JSON value | -|------------------------------|----------------------| +| ---------------------------- | -------------------- | | The hashless hex color quirk | `hashless-hex-color` | | The unitless length quirk | `unitless-length` | @@ -67,10 +67,11 @@ This generates `Keyword.h` and `Keyword.cpp`. All keyword values used by any property or media-feature need to be defined here. The generated code provides: -- A `Keyword` enum as used by `CSSKeywordValue` -- `Optional<Keyword> keyword_from_string(StringView)` to attempt to convert a string into a Keyword -- `StringView string_from_keyword(Keyword)` to convert a Keyword back into a string -- `bool is_css_wide_keyword(StringView)` which returns whether the string is one of the special "CSS-wide keywords" + +- A `Keyword` enum as used by `CSSKeywordValue` +- `Optional<Keyword> keyword_from_string(StringView)` to attempt to convert a string into a Keyword +- `StringView string_from_keyword(Keyword)` to convert a Keyword back into a string +- `bool is_css_wide_keyword(StringView)` which returns whether the string is one of the special "CSS-wide keywords" ## Enums.json @@ -85,10 +86,11 @@ This helps reduce repetition, for example the `border-*-style` properties all ac are implemented as a `line-style` enum. The generated code provides these for each enum, using "foo" as an example: -- A `Foo` enum for its values -- `Optional<Foo> keyword_to_foo(Keyword)` to convert a `Keyword` to a `Foo` -- `Keyword to_keyword(Foo)` to convert the `Foo` back to a `Keyword` -- `StringView to_string(Foo)` to convert the `Foo` directly to a string + +- A `Foo` enum for its values +- `Optional<Foo> keyword_to_foo(Keyword)` to convert a `Keyword` to a `Foo` +- `Keyword to_keyword(Foo)` to convert the `Foo` back to a `Keyword` +- `StringView to_string(Foo)` to convert the `Foo` directly to a string ## PseudoClasses.json @@ -100,11 +102,12 @@ function parameters - for identifier-style pseudo-classes it is left blank. The grammar is taken directly from the spec. The generated code provides: -- A `PseudoClass` enum listing every pseudo-class name -- `Optional<PseudoClass> pseudo_class_from_string(StringView)` to parse a string as a `PseudoClass` name -- `StringView pseudo_class_name(PseudoClass)` to convert a `PseudoClass` back into a string -- The `PseudoClassMetadata` struct which holds a representation of the data from the JSON file -- `PseudoClassMetadata pseudo_class_metadata(PseudoClass)` to retrieve that data + +- A `PseudoClass` enum listing every pseudo-class name +- `Optional<PseudoClass> pseudo_class_from_string(StringView)` to parse a string as a `PseudoClass` name +- `StringView pseudo_class_name(PseudoClass)` to convert a `PseudoClass` back into a string +- The `PseudoClassMetadata` struct which holds a representation of the data from the JSON file +- `PseudoClassMetadata pseudo_class_metadata(PseudoClass)` to retrieve that data ## MediaFeatures.json @@ -117,18 +120,19 @@ They are listed in the [`@media` descriptor table](https://www.w3.org/TR/mediaqu The definitions here are like a simplified version of the `Properties.json` definitions. | Field | Description | -|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | String. How the media-feature is evaluated, either `discrete` or `range`. | | `values` | Array of strings. These are directly taken from the spec, with keywords as they are, and `<>` around type names. Types may be `<boolean>`, `<integer>`, `<length>`, `<ratio>`, or `<resolution>`. | The generated code provides: -- A `MediaFeatureValueType` enum listing the possible value types -- A `MediaFeatureID` enum, listing each media-feature -- `Optional<MediaFeatureID> media_feature_id_from_string(StringView)` to convert a string to a `MediaFeatureID` -- `StringView string_from_media_feature_id(MediaFeatureID)` to convert a `MediaFeatureID` back to a string -- `bool media_feature_type_is_range(MediaFeatureID)` returns whether the media feature is a `range` type, as opposed to a `discrete` type -- `bool media_feature_accepts_type(MediaFeatureID, MediaFeatureValueType)` returns whether the media feature will accept values of this type -- `bool media_feature_accepts_keyword(MediaFeatureID, Keyword)` returns whether the media feature accepts this keyword + +- A `MediaFeatureValueType` enum listing the possible value types +- A `MediaFeatureID` enum, listing each media-feature +- `Optional<MediaFeatureID> media_feature_id_from_string(StringView)` to convert a string to a `MediaFeatureID` +- `StringView string_from_media_feature_id(MediaFeatureID)` to convert a `MediaFeatureID` back to a string +- `bool media_feature_type_is_range(MediaFeatureID)` returns whether the media feature is a `range` type, as opposed to a `discrete` type +- `bool media_feature_accepts_type(MediaFeatureID, MediaFeatureValueType)` returns whether the media feature will accept values of this type +- `bool media_feature_accepts_keyword(MediaFeatureID, Keyword)` returns whether the media feature accepts this keyword ## MathFunctions.json @@ -140,14 +144,15 @@ Each entry currently has a single property, `parameters`, which is an array of p Parameter definitions have the following properties: | Field | Description | -|------------|----------------------------------------------------------------------------------| +| ---------- | -------------------------------------------------------------------------------- | | `name` | String. Name of the parameter, as given in the spec. | | `type` | String. Accepted types for the parameter, as a single string, separated by `\|`. | | `required` | Boolean. Whether this parameter is required. | The generated code provides: -- A `MathFunction` enum listing the math functions -- The implementation of the CSS Parser's `parse_math_function()` method + +- A `MathFunction` enum listing the math functions +- The implementation of the CSS Parser's `parse_math_function()` method ## TransformFunctions.json @@ -159,12 +164,13 @@ Each entry currently has a single property, `parameters`, which is an array of p Parameter definitions have the following properties: | Field | Description | -|------------|----------------------------------------------| -| `type` | String. Accepted type for the parameter. | +| ---------- | -------------------------------------------- | +| `type` | String. Accepted type for the parameter. | | `required` | Boolean. Whether this parameter is required. | The generated code provides: -- A `TransformFunction` enum listing the transform functions -- `Optional<TransformFunction> transform_function_from_string(StringView)` to parse a string as a `TransformFunction` -- `StringView to_string(TransformFunction)` to convert a `TransformFunction` back to a string -- `TransformFunctionMetadata transform_function_metadata(TransformFunction)` to obtain metadata about the transform function, such as its parameter list + +- A `TransformFunction` enum listing the transform functions +- `Optional<TransformFunction> transform_function_from_string(StringView)` to parse a string as a `TransformFunction` +- `StringView to_string(TransformFunction)` to convert a `TransformFunction` back to a string +- `TransformFunctionMetadata transform_function_metadata(TransformFunction)` to obtain metadata about the transform function, such as its parameter list diff --git a/Documentation/Browser/LibWebFromLoadingToPainting.md b/Documentation/Browser/LibWebFromLoadingToPainting.md index 1ee80832d24..9fb3b2d3823 100644 --- a/Documentation/Browser/LibWebFromLoadingToPainting.md +++ b/Documentation/Browser/LibWebFromLoadingToPainting.md @@ -20,16 +20,16 @@ Due to the `document.write()` API, the parser also allows programmatic injection ### CSS parsing -* CSS parser -* Builds the CSSOM -* Values with variables can't be resolved until cascade, kept as "unresolved" values +- CSS parser +- Builds the CSSOM +- Values with variables can't be resolved until cascade, kept as "unresolved" values ### JS parsing & execution -* JS parser -* Builds JavaScript AST -* Interpreter runs AST -* Garbage collector (basic stop-the-world mark&sweep) +- JS parser +- Builds JavaScript AST +- Interpreter runs AST +- Garbage collector (basic stop-the-world mark&sweep) ### Style computation @@ -42,7 +42,7 @@ A CSS selector is represented by the CSS::Selector class. Given the following selector: ```css - #foo .bar.baz > img +#foo .bar.baz > img; ``` We get the following C++ object tree: @@ -69,10 +69,10 @@ The main optimization is a cache in StyleComputer that divides style rules into The C in CSS is for "cascading" and "the cascade" refers to the process where all the CSS declarations that should apply to a DOM element are evaluated in order. The order is determined by a number of factors, such as selector specificity, rule order within the style sheet. There's also per-property consideration of the `!important` annotation, which allows authors to override the normal cascade order. -* To compute the "computed style" for an element... -* Perform the CSS cascade to determine final property values -* Interpolate variables -* Absolutize, etc +- To compute the "computed style" for an element... +- Perform the CSS cascade to determine final property values +- Interpolate variables +- Absolutize, etc We separate CSS rules by their cascade origin. The two origins we're concerned with are "user-agent" and "author". If we supported custom user style sheets (we don't), they'd need a separate cascade origin as well. @@ -80,7 +80,7 @@ The cascade origin determines the processing order for rules. The "user-agent" s Note: the user-agent style is a built-in CSS style sheet that lives in the LibWeb source code [here](https://github.com/SerenityOS/serenity/blob/master/Userland/Libraries/LibWeb/CSS/Default.css). -The end product of style computation is a fully populated StyleProperties object. It has a StyleValue for each CSS::PropertyID. In spec parlance, these are the *computed* values. (Note that these are not the same as you get from `getComputedStyle()`, that API returns the *resolved* values.) +The end product of style computation is a fully populated StyleProperties object. It has a StyleValue for each CSS::PropertyID. In spec parlance, these are the _computed_ values. (Note that these are not the same as you get from `getComputedStyle()`, that API returns the _resolved_ values.) #### Resolving CSS custom properties ("variables") @@ -95,9 +95,9 @@ There isn't a 1:1 mapping between DOM nodes and layout nodes. Elements with `dis A number of tree fix-ups are also performed: -- To maintain the invariant that block containers only have all block-level children or all inline-level children, inline-level boxes with block-level siblings are wrapped in anonymous wrapper boxes. -- If an individual table component box is found outside the context of a full table, a set of anonymous table boxes are generated to compensate and ensure that there's always a fully-formed table. (FIXME: This is currently buggy..) -- For list item boxes (`display: list-item`), a box representing the marker is inserted if needed. +- To maintain the invariant that block containers only have all block-level children or all inline-level children, inline-level boxes with block-level siblings are wrapped in anonymous wrapper boxes. +- If an individual table component box is found outside the context of a full table, a set of anonymous table boxes are generated to compensate and ensure that there's always a fully-formed table. (FIXME: This is currently buggy..) +- For list item boxes (`display: list-item`), a box representing the marker is inserted if needed. ### Layout @@ -105,10 +105,11 @@ Layout starts at the ICB (initial containing block), which is the layout node th CSS says that the ICB should be the size of the viewport, so the very first thing layout does is assign these dimensions. Layout works through a mechanism call formatting contexts. CSS defines a number of different formatting contexts: -- Block Formatting Context (BFC) -- Inline Formatting Context (IFC) -- Table Formatting Context (TFC) -- Flex Formatting Context (FFC) + +- Block Formatting Context (BFC) +- Inline Formatting Context (IFC) +- Table Formatting Context (TFC) +- Flex Formatting Context (FFC) In LibWeb, to simplify the layout model, we also define our own SVGFormattingContext for embedded SVG content. This isn't part of the SVG specification, but simplifies the implementation. @@ -128,9 +129,9 @@ The job of IFC is to generate line boxes. Line boxes are essentially a sequence There are three main classes involved in inline-level layout: -- InlineFormattingContext (IFC) -- LineBuilder -- InlineLevelIterator +- InlineFormattingContext (IFC) +- LineBuilder +- InlineLevelIterator IFC drives the high-level loop by creating a LineBuilder and an InlineLevelIterator. It then traverses the inline-level content within the IFC containing block, one item at a time, by calling InlineLevelIterator::next(). @@ -165,5 +166,5 @@ The stacking context tree is rooted at the ICB, and can have zero or more descen Painting follows the order specified in the CSS2 appendix E. The rules are quite involved, but two main things to know about: -- Painting is driven through stacking contexts, which are painted back-to-front (stacking context tree order) -- Painting is performed in *phases*. For each stacking context, we paint in order: backgrounds & borders, floats, backgrounds & borders for inline and replaced content, foreground (text), focus outlines and overlays. +- Painting is driven through stacking contexts, which are painted back-to-front (stacking context tree order) +- Painting is performed in _phases_. For each stacking context, we paint in order: backgrounds & borders, floats, backgrounds & borders for inline and replaced content, foreground (text), focus outlines and overlays. diff --git a/Documentation/Browser/ProcessArchitecture.md b/Documentation/Browser/ProcessArchitecture.md index c08d71d3786..e74be8760c2 100644 --- a/Documentation/Browser/ProcessArchitecture.md +++ b/Documentation/Browser/ProcessArchitecture.md @@ -1,6 +1,6 @@ # SerenityOS Browser process architecture -*NOTE: This document is partly aspirational, in that the state of the code does not yet fully reflect what's described here. Implementation is underway.* +_NOTE: This document is partly aspirational, in that the state of the code does not yet fully reflect what's described here. Implementation is underway._ The SerenityOS web browser (**"Browser"**) uses a multi-process architecture to improve stability and security in the face of arbitrary (and possibly hostile) web content. @@ -10,7 +10,7 @@ The SerenityOS web browser (**"Browser"**) uses a multi-process architecture to Every instance of the **Browser** application can have one or more tabs open. Each tab has a unique **WebContent** service process spawned on its behalf. -Two important aspects of web browsing are further separated from the **WebContent** process: *network requests* and *image decoding*, segregated to the **RequestServer** and **ImageDecoder** processes respectively. +Two important aspects of web browsing are further separated from the **WebContent** process: _network requests_ and _image decoding_, segregated to the **RequestServer** and **ImageDecoder** processes respectively. All processes are aggressively sandboxed using the `pledge()` and `unveil()` mechanisms. Furthermore, all processes except **Browser** run as an unprivileged user, separate from the primary logged-in desktop user. diff --git a/Documentation/BuildInstructions.md b/Documentation/BuildInstructions.md index 3f5c036f0d1..d415b685d90 100644 --- a/Documentation/BuildInstructions.md +++ b/Documentation/BuildInstructions.md @@ -9,6 +9,7 @@ Make sure you have all the dependencies installed: ```console sudo apt install build-essential cmake curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs ninja-build qemu-system-gui qemu-system-x86 qemu-utils ccache rsync unzip texinfo libssl-dev ``` + Optional: `fuse2fs` for [building images without root](https://github.com/SerenityOS/serenity/pull/11224). #### GCC 13 or Clang 17+ @@ -61,11 +62,11 @@ attempt to build CMake from source if the version on your path is older than 3.2 If you have previously compiled SerenityOS with an older or distribution-provided version of CMake, you will need to manually remove the CMakeCache.txt files, as these files reference the older CMake version and path. + ```console rm Build/*/CMakeCache.txt ``` - ### Windows If you're on Windows you can use WSL2 to build SerenityOS. Please have a look at the [Windows guide](BuildInstructionsWindows.md) @@ -76,6 +77,7 @@ for details. ```console sudo pacman -S --needed base-devel cmake curl mpfr libmpc gmp e2fsprogs ninja qemu-desktop qemu-system-aarch64 ccache rsync unzip ``` + Optional: `fuse2fs` for [building images without root](https://github.com/SerenityOS/serenity/pull/11224), and `clang llvm llvm-libs` for building with Clang. ### SerenityOS @@ -96,8 +98,8 @@ This is best achieved by adding `ln -sf /usr/local/bin/bash mnt/bin/sh` to your There is also documentation for installing the build prerequisites for some less commonly used systems: -* [Other Linux distributions and \*NIX systems](BuildInstructionsOther.md) -* [macOS](BuildInstructionsMacOS.md) +- [Other Linux distributions and \*NIX systems](BuildInstructionsOther.md) +- [macOS](BuildInstructionsMacOS.md) ## Build @@ -138,11 +140,12 @@ Ports might also have additional dependencies. Most prominently, you may need: `rename`, `zip`. For select ports you might need slightly more exotic dependencies such as: -- `file` (version 5.44 exactly, for file) -- `libpython3-dev` (most prominently for boost) -- `lua` (for luarocks) -- `openjdk-17-jdk` (to compile OpenJDK) -- `rake` (to build mruby). + +- `file` (version 5.44 exactly, for file) +- `libpython3-dev` (most prominently for boost) +- `lua` (for luarocks) +- `openjdk-17-jdk` (to compile OpenJDK) +- `rake` (to build mruby). You may also need a symlink from "/usr/bin/python" to "/usr/bin/python3"; some ports depend on "python" existing, most notably ninja. diff --git a/Documentation/BuildInstructionsLadybird.md b/Documentation/BuildInstructionsLadybird.md index 4fc8963db6f..a5ae3765641 100644 --- a/Documentation/BuildInstructionsLadybird.md +++ b/Documentation/BuildInstructionsLadybird.md @@ -28,16 +28,19 @@ sudo pacman -S --needed base-devel cmake libgl ninja qt6-base qt6-tools qt6-wayl ``` On Fedora or derivatives: + ``` sudo dnf install cmake libglvnd-devel ninja-build qt6-qtbase-devel qt6-qttools-devel qt6-qtwayland-devel qt6-qtmultimedia-devel ccache ``` On openSUSE: + ``` sudo zypper install cmake libglvnd-devel ninja qt6-base-devel qt6-multimedia-devel qt6-tools-devel qt6-wayland-devel ccache ``` On NixOS or with Nix: + ```console nix develop .#ladybird @@ -46,6 +49,7 @@ nix develop .#ladybird --command bash ``` On NixOS or with Nix using your host `nixpkgs` and the legacy `nix-shell` tool: + ```console nix-shell Ladybird @@ -63,6 +67,7 @@ brew install cmake ninja ccache ``` If you also plan to use the Qt chrome on macOS: + ``` brew install qt ``` @@ -76,6 +81,7 @@ pfexec pkg install cmake ninja clang-17 libglvnd qt6 ``` On Haiku: + ``` pkgman install cmake ninja cmd:python3 qt6_base_devel qt6_multimedia_devel qt6_tools_devel openal_devel ``` @@ -98,8 +104,9 @@ The simplest way to build and run ladybird is via the serenity.sh script: ``` The above commands will build Ladybird with one of the following browser chromes, depending on the platform: -* [AppKit](https://developer.apple.com/documentation/appkit?language=objc) - The native chrome on macOS. -* [Qt](https://doc.qt.io/qt-6/) - The chrome used on all other platforms. + +- [AppKit](https://developer.apple.com/documentation/appkit?language=objc) - The native chrome on macOS. +- [Qt](https://doc.qt.io/qt-6/) - The chrome used on all other platforms. The Qt chrome is available on platforms where it is not the default as well. To build the Qt chrome, install the Qt dependencies for your platform, and enable the Qt chrome via CMake: @@ -130,7 +137,7 @@ Ladybird requires resource files from the serenity/Base/res directory in order t icons, fonts, and other theming information. The serenity.sh script calls into custom CMake targets that set these variables, and ensure that the $PWD is set properly to allow execution from the build directory. To run the built binary without using the script, one can either directly invoke the -ninja rules or install ladybird using the provided CMake install rules. See the ``Custom CMake build directory`` +ninja rules or install ladybird using the provided CMake install rules. See the `Custom CMake build directory` section below for details. ### Custom CMake build directory @@ -141,7 +148,7 @@ CMakeLists.txt, or via the CMakeLists.txt found in the Ladybird directory. For d Ladybird as the source directory will give the desired results. The install rules in Ladybird/cmake/InstallRules.cmake define which binaries and libraries will be -installed into the configured CMAKE_PREFIX_PATH or path passed to ``cmake --install``. +installed into the configured CMAKE_PREFIX_PATH or path passed to `cmake --install`. Note that when using a custom build directory rather than Meta/serenity.sh, the user may need to provide a suitable C++ compiler (g++ >= 13, clang >= 14, Apple Clang >= 14.3) via the CMAKE_CXX_COMPILER and @@ -155,16 +162,19 @@ ninja -C Build/ladybird run ``` To automatically run in gdb: + ``` ninja -C Build/ladybird debug ``` To run without ninja rule on non-macOS systems: + ``` ./Build/ladybird/bin/Ladybird ``` To run without ninja rule on macOS: + ``` open -W --stdout $(tty) --stderr $(tty) ./Build/ladybird/bin/Ladybird.app diff --git a/Documentation/BuildInstructionsMacOS.md b/Documentation/BuildInstructionsMacOS.md index 74d50dc07a3..b03dae31841 100644 --- a/Documentation/BuildInstructionsMacOS.md +++ b/Documentation/BuildInstructionsMacOS.md @@ -5,6 +5,7 @@ This installation guide assumes that you have [Homebrew](https://brew.sh) and Xcode installed. You need to open Xcode at least once for it to install the required tools. Before you build, you must set your command line tools to Xcode's tools instead of the ones installed via Homebrew: + ```console sudo xcode-select --switch /Applications/Xcode.app ``` diff --git a/Documentation/BuildInstructionsOther.md b/Documentation/BuildInstructionsOther.md index 6de8aeffefd..ee734ef5d2e 100644 --- a/Documentation/BuildInstructionsOther.md +++ b/Documentation/BuildInstructionsOther.md @@ -5,6 +5,7 @@ ```console sudo dnf install texinfo binutils-devel curl cmake mpfr-devel libmpc-devel gmp-devel e2fsprogs ninja-build patch ccache rsync @"C Development Tools and Libraries" @Virtualization ``` + Optional: `e2fsprogs` package for [building images without root](https://github.com/SerenityOS/serenity/pull/11224). ## openSUSE @@ -61,6 +62,7 @@ apk add qemu qemu-system-x86_64 qemu-img qemu-ui-gtk qemu-audio-pa # build tools (samurai is a drop-in replacement for ninja) apk add cmake e2fsprogs grub-bios samurai mpc1-dev mpfr-dev gmp-dev ccache rsync texinfo ``` + Optional: `fuse2fs` for [building images without root](https://github.com/SerenityOS/serenity/pull/11224). ## OpenBSD prerequisites @@ -74,4 +76,5 @@ doas pkg_add bash cmake g++ gcc git gmake gmp ninja ccache rsync coreutils qemu ```console pkg install qemu bash cmake coreutils e2fsprogs fusefs-ext2 gcc11 git gmake ninja sudo gmp mpc mpfr ccache rsync ``` + Optional: `fusefs-ext2` for [building images without root](https://github.com/SerenityOS/serenity/pull/11224). diff --git a/Documentation/BuildInstructionsWindows.md b/Documentation/BuildInstructionsWindows.md index 9bd1abecf5a..3ccdc4c858b 100644 --- a/Documentation/BuildInstructionsWindows.md +++ b/Documentation/BuildInstructionsWindows.md @@ -7,9 +7,10 @@ WSL Version 2 requires Windows 10 version 2004 or higher, with OS Build 19041 or [get WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Once installed, you will need to make sure the distribution you want to use (and the new default) is using Version 2: -- `wsl -l -v` lists distros and versions,<br/> -- `wsl --set-version <distro> <version>` is used to convert a distro to another version, and<br/> -- `wsl --set-default-version 2` will set the default version for all new distros (if desired.)<br/> + +- `wsl -l -v` lists distros and versions,<br/> +- `wsl --set-version <distro> <version>` is used to convert a distro to another version, and<br/> +- `wsl --set-default-version 2` will set the default version for all new distros (if desired.)<br/> Next, go to [BuildInstructions.md](https://github.com/SerenityOS/serenity/blob/master/Documentation/BuildInstructions.md#prerequisites) and follow the instructions for your chosen Linux environment, to get the needed build tools. diff --git a/Documentation/BuildProfilingInstructions.md b/Documentation/BuildProfilingInstructions.md index 7f8e2992fb6..6c9c4e7a31b 100644 --- a/Documentation/BuildProfilingInstructions.md +++ b/Documentation/BuildProfilingInstructions.md @@ -21,6 +21,7 @@ You also need to make sure `ninjatracing` is marked as executable, and available ### Usage First, we need to clean the build (and `ccache` if present) to make sure every file gets compiled and gives a meaningful time reading. + ```console ninja clean @@ -28,6 +29,7 @@ ccache --clear ``` Then, execute ninja as normal: + ```console ninja ``` diff --git a/Documentation/CLionConfiguration.md b/Documentation/CLionConfiguration.md index 2e9234afc4e..b4fc83cd015 100644 --- a/Documentation/CLionConfiguration.md +++ b/Documentation/CLionConfiguration.md @@ -11,6 +11,7 @@ After opening the `serenity` repository in CLion as a new project, the "`Open Pr > _CMake will complain with any other build type, make sure to use `Default` so that `CMAKE_BUILD_TYPE` is empty in the `Build/x86_64/CMakeCache.txt` file._ `CMake Options`: + ``` -DCMAKE_PREFIX_PATH=$CMakeProjectDir$/Build/lagom-install -DCMAKE_TOOLCHAIN_FILE=$CMakeProjectDir$/Build/x86_64/CMakeToolchain.txt @@ -36,15 +37,17 @@ Source files are copied to the `Build` directory during the build, if you do not in search results. This is often confusing, unintuitive, and can result in you losing changes you have made to files. To exclude these files navigate to the `Project` tool window, right-click the `Build` folder and select `Mark Directory as | Excluded`. If you want to exclude Toolchain files as well, follow the same procedure with the following paths: -- `Toolchain/Local` -- `Toolchain/Tarballs` -- `Toolchain/Build` + +- `Toolchain/Local` +- `Toolchain/Tarballs` +- `Toolchain/Build` ## Include headers and source files for code insight To get proper code insight mark the folders `AK`, `Kernel` and `Userland` by right-clicking on them and selecting `Mark Directory as | Project Sources and Headers`. -A symptom of this not being configured correctly is CLion giving a warning for every single file: +A symptom of this not being configured correctly is CLion giving a warning for every single file: + > The file does not belong to any project target, code insight features might not work properly. ## Code Generation Settings @@ -55,6 +58,7 @@ To make code generated by CLion match the SerenityOS coding style, import the `C ## Quick switching between Kernel and Userland targets In order to let CLion know what kind of code you're currently working on (Kernel / Userland) to make sure it parses and displays the correct half of statements like this: + ```c++ #ifdef KERNEL ... @@ -62,6 +66,7 @@ In order to let CLion know what kind of code you're currently working on (Kernel ... #endif ``` + You need to add build configurations for each: Click on one of the buttons below (top right of the IDE) - If you have the second one, press Edit Configurations after the dropdown box opens, then press CTRL+A to select the 1000s of automatically generated targets, and then press Delete to remove them. @@ -88,16 +93,16 @@ Note that following will only help if you don't use an X-window server to access It is possible to install qemu natively on Windows and allow WSL to use it instead of installing qemu first on (wsl) linux and then use X server to launch serenity inside of it. Check the updated manual [here](BuildInstructionsWindows.md). -- Locate the terminal emulator for your linux distribution. -Open CMD with elevated privileges and cd to `C:/Program Files/WindowsApps/`. -The directory is usually hidden and requires additional privileges. You should be able to cd as administrator. -`dir` and look for your distribution in directory names. In case of Ubuntu, it starts with `CanonicalGroupLimited.Ubuntu20.04onWindows_2004.2020.424.0_x64`. -cd to it. The directory should contain the shell executable. In my case it's named `ubuntu2004.exe`. -Copy `absolute/path/to/ubuntu2004.exe`. +- Locate the terminal emulator for your linux distribution. + Open CMD with elevated privileges and cd to `C:/Program Files/WindowsApps/`. + The directory is usually hidden and requires additional privileges. You should be able to cd as administrator. + `dir` and look for your distribution in directory names. In case of Ubuntu, it starts with `CanonicalGroupLimited.Ubuntu20.04onWindows_2004.2020.424.0_x64`. + cd to it. The directory should contain the shell executable. In my case it's named `ubuntu2004.exe`. + Copy `absolute/path/to/ubuntu2004.exe`. -- Go to your IDE settings: `File->Settings->Tools->Terminal` and paste the path you just copied to `shell path`. Click OK. +- Go to your IDE settings: `File->Settings->Tools->Terminal` and paste the path you just copied to `shell path`. Click OK. -- Close CLion and restart. +- Close CLion and restart. The default IDE terminal should now be changed to WSL, and now you can run `CLion/run.sh`. You may also want to copy `serenity/Meta/CLion/run.sh` to your project directory and run it from there, so that you don't have to fight with git every time you modify the script. diff --git a/Documentation/CodingStyle.md b/Documentation/CodingStyle.md index f25bca4bd90..0de5532eaac 100644 --- a/Documentation/CodingStyle.md +++ b/Documentation/CodingStyle.md @@ -8,14 +8,13 @@ This document describes the coding style used for C++ code in the Serenity Opera We'll definitely be tweaking and amending this over time, so let's consider it a living document. :) - ### Names -A combination of CamelCase, snake\_case, and SCREAMING\_CASE: +A combination of CamelCase, snake_case, and SCREAMING_CASE: -- Use CamelCase (Capitalize the first letter, including all letters in an acronym) in a class, struct, or namespace name -- Use snake\_case (all lowercase, with underscores separating words) for variable and function names -- Use SCREAMING\_CASE for constants (both global and static member variables) +- Use CamelCase (Capitalize the first letter, including all letters in an acronym) in a class, struct, or namespace name +- Use snake_case (all lowercase, with underscores separating words) for variable and function names +- Use SCREAMING_CASE for constants (both global and static member variables) ###### Right: @@ -248,7 +247,6 @@ for (auto& child : children) child->do_child_thing(); ``` - #### OK: ```cpp @@ -386,8 +384,8 @@ signed int c; // Doesn't omit "signed". For types with methods, prefer `class` over `struct`. -* For classes, make public getters and setters, keep members private with `m_` prefix. -* For structs, let everything be public and skip the `m_` prefix. +- For classes, make public getters and setters, keep members private with `m_` prefix. +- For structs, let everything be public and skip the `m_` prefix. ###### Right: @@ -516,7 +514,7 @@ draw_jpg(); // FIXME(joe): Make this code handle jpg in addition to the png supp draw_jpg(); // TODO: Make this code handle jpg in addition to the png support. ``` -Explain *why* the code does something. The code itself should already say what is happening. +Explain _why_ the code does something. The code itself should already say what is happening. ###### Right: @@ -646,16 +644,17 @@ const Salt& m_salt; Before you consider a cast, please see if your problem can be solved another way that avoids the visual clutter. -- Integer constants can be specified to have (some) specific sizes with postfixes like `u, l, ul` etc. The same goes for single-precision floating-point constants with `f`. -- Working with smaller-size integers in arithmetic expressions is hard because of [implicit promotion](https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules). Generally, it is fine to use `int` and other "large" types in local variables, and possibly cast at the end. -- If you `const_cast`, _really_ consider whether your APIs need to be adjusted in terms of their constness. Does the member function you're writing actually make sense to be `const`? -- If you do checked casts between base and derived types, also consider your APIs. For example: Does the function being called actually need to receive the more general type or is it fine with the more specialized type? +- Integer constants can be specified to have (some) specific sizes with postfixes like `u, l, ul` etc. The same goes for single-precision floating-point constants with `f`. +- Working with smaller-size integers in arithmetic expressions is hard because of [implicit promotion](https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules). Generally, it is fine to use `int` and other "large" types in local variables, and possibly cast at the end. +- If you `const_cast`, _really_ consider whether your APIs need to be adjusted in terms of their constness. Does the member function you're writing actually make sense to be `const`? +- If you do checked casts between base and derived types, also consider your APIs. For example: Does the function being called actually need to receive the more general type or is it fine with the more specialized type? If you _do_ need to cast: **Don't use C-style casts**. The C-style cast has [complex behavior](https://en.cppreference.com/w/c/language/cast) that is undesired in many instances. Be aware of what sort of type conversion the code is trying to achieve, and use the appropriate (!) C++ cast operator, like `static_cast`, `reinterpret_cast`, `bit_cast`, `dynamic_cast` etc. There is a single exception to this rule: marking a function parameter as used with `(void)parameter;`. ###### Right: + ```cpp MyParentClass& object = get_object(); // Verify the type... @@ -678,6 +677,7 @@ return const_cast<SeekableStream*>(this)->seek(0, SeekMode::FromCurrentPosition) ``` ###### Wrong: + ```cpp // These should be static_cast. size_t mask_length = (size_t)((u8)-1) + 1; @@ -695,6 +695,7 @@ Curly braces may only be omitted from `if`/`else`/`for`/`while`/etc. statement b Additionally, if any body of a connected if/else statement requires curly braces according to this rule, all of them do. ###### Right: + ```cpp if (condition) foo(); diff --git a/Documentation/EmacsConfiguration.md b/Documentation/EmacsConfiguration.md index 5591545cf26..0e9f0700cf6 100644 --- a/Documentation/EmacsConfiguration.md +++ b/Documentation/EmacsConfiguration.md @@ -9,16 +9,16 @@ can use the following `.clangd` file placed in the project root: ```yaml CompileFlags: - CompilationDatabase: Build/x86_64 - Add: - - "-D__serenity__" - - "-UNO_TLS" - - "-I/path/to/serenity/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/13.1.0" - - "-I/path/to/serenity/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/13.1.0/x86_64-pc-serenity" + CompilationDatabase: Build/x86_64 + Add: + - "-D__serenity__" + - "-UNO_TLS" + - "-I/path/to/serenity/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/13.1.0" + - "-I/path/to/serenity/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/13.1.0/x86_64-pc-serenity" Diagnostics: - UnusedIncludes: None - MissingIncludes: None + UnusedIncludes: None + MissingIncludes: None ``` You will need to change `/path/to/serenity` and change `13.1.0` to @@ -45,18 +45,18 @@ that is needed by `clangd`. There are a few different ways to specify which clangd to use: -- By default, without configuration `lsp-mode` will try to find and use your system `clangd`. This is the easiest solution, but your system clangd might be out of date. -- You can manually specify any `clangd` binary with `lsp-clangd-binary-path`, as shown in the use-package example above. -- You can have `lsp-mode` manage your `clangd` installation with emacs' `lsp-install-server`. This will install a `clangd` binary for you. -- You can build the LLVM toolchain, including `clangd`, from Serenity's repository. This is an advanced option that is not currently documented. +- By default, without configuration `lsp-mode` will try to find and use your system `clangd`. This is the easiest solution, but your system clangd might be out of date. +- You can manually specify any `clangd` binary with `lsp-clangd-binary-path`, as shown in the use-package example above. +- You can have `lsp-mode` manage your `clangd` installation with emacs' `lsp-install-server`. This will install a `clangd` binary for you. +- You can build the LLVM toolchain, including `clangd`, from Serenity's repository. This is an advanced option that is not currently documented. ### clang-format There are multiple packages to handle auto formatting with `clang-format`, within emacs. Choose what works best for your setup: -- [format-all-mode](https://github.com/lassik/emacs-format-all-the-code) -- [clang-format-plus](https://github.com/SavchenkoValeriy/emacs-clang-format-plus) +- [format-all-mode](https://github.com/lassik/emacs-format-all-the-code) +- [clang-format-plus](https://github.com/SavchenkoValeriy/emacs-clang-format-plus) Alternatively, this can be done without additional packages, using `lsp-mode`. You can use the following `.dir-locals.el` file placed in the project root: diff --git a/Documentation/FAQ.md b/Documentation/FAQ.md index 9a796fe86ce..a3a75db4606 100644 --- a/Documentation/FAQ.md +++ b/Documentation/FAQ.md @@ -34,14 +34,14 @@ More specifically, SerenityOS does not have a package manager that allows you to The supported method to use third-party software is by compiling ports that can be found in the [Ports directory](../Ports). A port is a piece of software that can optionally be installed, might not have been built by us, but supports running on SerenityOS. They act quite similarly to packages, each coming with their own install script. The significant difference is that ports are always built from source. -Currently when running the system in a virtual machine, ports should be cross compiled on the host, and added to the file system image before booting. It is possible to compile ports on SerenityOS itself, which requires quite a bit of manual work. At the moment, this is not a recommended or actively supported workflow. In the future, this process *may* be supported more easily with the `pkg` tool. If you are interested in contributing in this regard, take a look at the #package-manager channel on Discord. +Currently when running the system in a virtual machine, ports should be cross compiled on the host, and added to the file system image before booting. It is possible to compile ports on SerenityOS itself, which requires quite a bit of manual work. At the moment, this is not a recommended or actively supported workflow. In the future, this process _may_ be supported more easily with the `pkg` tool. If you are interested in contributing in this regard, take a look at the #package-manager channel on Discord. In regards to SerenityOS components themselves, it is possible to [exclude some of them](./AdvancedBuildInstructions.md#component-configuration) from the build at compile time. ## Why is there an MP3 implementation in SerenityOS if MP3 is protected by patents? -*This section is informational; we are not lawyers and this is not legal advice. Consult a qualified lawyer if you have legal questions regarding your use of SerenityOS software.* +_This section is informational; we are not lawyers and this is not legal advice. Consult a qualified lawyer if you have legal questions regarding your use of SerenityOS software._ MP3 was indeed originally protected by patents, preventing certain uses of the format. All MP3 patents, however, have expired since at least 2017, depending on where a specific patent was registered. Therefore, we believe it to be completely legal to implement MP3 as 2-clause BSD licensed software without acquiring patent licenses. -*However*, this does not apply to many other multimedia formats, such as the popular H.264 (AVC) and H.265 (HEVC) video codecs or the JPEG 2000 image format. As long as there is any reason to believe that a format is covered by patents, there will not be an implementation in the SerenityOS monorepo, as we believe this to be incompatible with the BSD 2-clause license in general. *However however*, third-party ports with differing licenses can provide implementations for these formats, such as ffmpeg. Depending on your situation and/or use case, using this third-party software might not be legal (for example, see the [ffmpeg information on the same topic](https://ffmpeg.org/legal.html)). Everything regarding the legal situation of the SerenityOS code is handled by [our license](../LICENSE), everything regarding the legal situation of third-party code is handled by the license of the particular software. +_However_, this does not apply to many other multimedia formats, such as the popular H.264 (AVC) and H.265 (HEVC) video codecs or the JPEG 2000 image format. As long as there is any reason to believe that a format is covered by patents, there will not be an implementation in the SerenityOS monorepo, as we believe this to be incompatible with the BSD 2-clause license in general. _However however_, third-party ports with differing licenses can provide implementations for these formats, such as ffmpeg. Depending on your situation and/or use case, using this third-party software might not be legal (for example, see the [ffmpeg information on the same topic](https://ffmpeg.org/legal.html)). Everything regarding the legal situation of the SerenityOS code is handled by [our license](../LICENSE), everything regarding the legal situation of third-party code is handled by the license of the particular software. diff --git a/Documentation/HardwareCompatibility.md b/Documentation/HardwareCompatibility.md index 0bcd4fb85eb..e962416179f 100644 --- a/Documentation/HardwareCompatibility.md +++ b/Documentation/HardwareCompatibility.md @@ -6,33 +6,33 @@ Serenity boots to a graphical desktop on all machines unless otherwise noted. ### Network Adapters -| Model | Notes | -| ---------------------------------------- | ----------------------------- | -| Intel 82545XX | Also known as e1000 | -| Intel 82574L | Also known as e1000e | -| RTL8168/8111 (Variants B, E, E-VL & H) | Other variants are WIP | +| Model | Notes | +| -------------------------------------- | ---------------------- | +| Intel 82545XX | Also known as e1000 | +| Intel 82574L | Also known as e1000e | +| RTL8168/8111 (Variants B, E, E-VL & H) | Other variants are WIP | ### Desktop machines -| Make and model | Notes | -| ---------------------------------------- | ----------------------------- | -| Viglen VM3B | Has onboard RTL8139 NIC | +| Make and model | Notes | +| -------------- | ----------------------- | +| Viglen VM3B | Has onboard RTL8139 NIC | ### Laptops, notebooks and netbooks -| Make and model | Notes | -| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Dell Inspiron mini 10 | ICH7-M SATA controller works in IDE mode, RTL810xE NIC and Intel NM10 audio unsupported | -| HP 15-ac108na | Pentium 3825U, Wildcat Point Chipset. AHCI works. Keyboard and trackpad work (both are PS2), trackpad scrolling/gestures don't work. RTL810xE NIC, RTL8723BE Wireless NIC, xHCI and Intel HDA audio unsupported. | -| Lenovo Ideapad 510s | Sunrise Point Chipset. AHCI works. Keyboard and trackpad work (both are PS2), RTL810xE NIC, Intel 3165 Wireless NIC, USB and Intel HDA audio unsupported. | +| Make and model | Notes | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Dell Inspiron mini 10 | ICH7-M SATA controller works in IDE mode, RTL810xE NIC and Intel NM10 audio unsupported | +| HP 15-ac108na | Pentium 3825U, Wildcat Point Chipset. AHCI works. Keyboard and trackpad work (both are PS2), trackpad scrolling/gestures don't work. RTL810xE NIC, RTL8723BE Wireless NIC, xHCI and Intel HDA audio unsupported. | +| Lenovo Ideapad 510s | Sunrise Point Chipset. AHCI works. Keyboard and trackpad work (both are PS2), RTL810xE NIC, Intel 3165 Wireless NIC, USB and Intel HDA audio unsupported. | ### Motherboards -| Make and model | Notes | -| ---------------------------------------- | ----------------------------------------------------------------| -| Intel Desktop Board D915GAG / D915PSY | Pentium 4 HT CPU | -| Intel Desktop Board D875PBZ | Pentium 4 HT CPU | -| Gigabyte G31M-ES2L | ICH7 2009 machine with IDE controller only | -| Asus PRIME B360-PLUS | Has only one PS2 port, AHCI works | -| Asus H81M-K | w/ Intel Core i3-4170, AHCI works | -| Acer OEM Motherboard, H57H-AM2 | w/ Intel Core i5-760, AHCI work (graphics not tested) | +| Make and model | Notes | +| ------------------------------------- | ----------------------------------------------------- | +| Intel Desktop Board D915GAG / D915PSY | Pentium 4 HT CPU | +| Intel Desktop Board D875PBZ | Pentium 4 HT CPU | +| Gigabyte G31M-ES2L | ICH7 2009 machine with IDE controller only | +| Asus PRIME B360-PLUS | Has only one PS2 port, AHCI works | +| Asus H81M-K | w/ Intel Core i3-4170, AHCI works | +| Acer OEM Motherboard, H57H-AM2 | w/ Intel Core i5-760, AHCI work (graphics not tested) | diff --git a/Documentation/HelixConfiguration.md b/Documentation/HelixConfiguration.md index 0c6ece27f36..74106dd9a07 100644 --- a/Documentation/HelixConfiguration.md +++ b/Documentation/HelixConfiguration.md @@ -1,18 +1,21 @@ # Helix Configuration + Helix comes with support for `clangd` and `clang-format` out of the box! However, a small bit of configuration is needed for it to work correctly with SerenityOS. The following `.clangd` should be placed in the project root: + ```yaml CompileFlags: - CompilationDatabase: Build/x86_64 # Or whatever architecture you're targeting, e.g. aarch64 - Add: [-D__serenity__] + CompilationDatabase: Build/x86_64 # Or whatever architecture you're targeting, e.g. aarch64 + Add: [-D__serenity__] Diagnostics: - UnusedIncludes: None - MissingIncludes: None + UnusedIncludes: None + MissingIncludes: None ``` You also need to configure the clangd server to detect headers properly from the Serenity toolchain. To do this, create a `.helix/languages.toml` file in the project root: + ```toml [language-server.serenity] command = "clangd" diff --git a/Documentation/HighDPI.md b/Documentation/HighDPI.md index 0b31b27335e..1be4464bf73 100644 --- a/Documentation/HighDPI.md +++ b/Documentation/HighDPI.md @@ -1,30 +1,26 @@ -HighDPI design -============== +# HighDPI design -Background ----------- +## Background -- macOS: Only integer scale factors at app level. Can stretch final composited framebuffer at very end for non-integer display scales. - - advantages: simple programming model, still fairly flexible; scaling at end produces coherent final image - - disadvantages: needs 4x memory even for 1.5x scale; scaling at very makes final image less detailed than it could be +- macOS: Only integer scale factors at app level. Can stretch final composited framebuffer at very end for non-integer display scales. -- Android: Many (but discrete) scale levels (ldpi (0.75x), mdpi, hdpi (1.5x), xhdpi (2x), xxhdpi (3x), xxhdpi (4x)) + - advantages: simple programming model, still fairly flexible; scaling at end produces coherent final image + - disadvantages: needs 4x memory even for 1.5x scale; scaling at very makes final image less detailed than it could be -- Windows: has "not recommended" free form text entry for scale factor between 100% and 500%. +- Android: Many (but discrete) scale levels (ldpi (0.75x), mdpi, hdpi (1.5x), xhdpi (2x), xxhdpi (3x), xxhdpi (4x)) + +- Windows: has "not recommended" free form text entry for scale factor between 100% and 500%. Integer scale factors are needed in any case so let's get that working first. Actually, let's focus on just 2x for now. +## Desired end state -Desired end state ------------------ +- All rects (Window and Widget rects, mouse cursor, even bitmap sizes) are in "logical" coordinates, which is the same as pixels at 1x scale, as much as possible. +- If something needs to be in pixels, its name starts with `physical_`. Physical coordinates should as much as possible not cross API boundaries. +- Jury's still out if logical coordinates should stay ints. Probably, but it means mouse cursor etc only have point resolution, not pixel resolution +- We should have something that can store a collection of (lazily-loaded?) bitmaps and fonts that each represent a single image / font at different scale levels, and at paint time the right representation is picked for the current scale -- All rects (Window and Widget rects, mouse cursor, even bitmap sizes) are in "logical" coordinates, which is the same as pixels at 1x scale, as much as possible. -- If something needs to be in pixels, its name starts with `physical_`. Physical coordinates should as much as possible not cross API boundaries. -- Jury's still out if logical coordinates should stay ints. Probably, but it means mouse cursor etc only have point resolution, not pixel resolution -- We should have something that can store a collection of (lazily-loaded?) bitmaps and fonts that each represent a single image / font at different scale levels, and at paint time the right representation is picked for the current scale - -Resource loading ----------------- +## Resource loading Resources such as icons, cursors, bitmap fonts are scale-dependent: In HighDPI modes, different resources need to be loaded. @@ -74,58 +70,58 @@ Possible new structures: 1. Have "1x", "2x" folders right inside res and then mirror folder structures inside them: - res/ - 1x/ - cursors/ - 16x16/ - emoji/ - ... - 2x/ - cursors/ - 16x16/ - emoji/ - ... + res/ + 1x/ + cursors/ + 16x16/ + emoji/ + ... + 2x/ + cursors/ + 16x16/ + emoji/ + ... 2. Instead of having the 1x/2x fork at the root, have it at each leaf: - res/ - cursors/ - 1x/ - arrowx2y2.png - ... - 2x/ - arrowx2y2.png - ... - emoji/ - 1/ - U+1F346.png - ... - 2/ - U+1F346.png - ... - ... + res/ + cursors/ + 1x/ + arrowx2y2.png + ... + 2x/ + arrowx2y2.png + ... + emoji/ + 1/ + U+1F346.png + ... + 2/ + U+1F346.png + ... + ... 3. Use filename suffixes instead of directories (similar to macOS): - res/ - cursors/ - arrowx2y2.png - arrowx2y2@2x.png - ... - emoji/ - U+1F346.png - U+1F346@2x.png - ... + res/ + cursors/ + arrowx2y2.png + arrowx2y2@2x.png + ... + emoji/ + U+1F346.png + U+1F346@2x.png + ... 4. Use suffixes on directory instead of subdirectory: - res/ - cursors/ - arrowx2y2.png - ... - cursors-2x/ - arrowx2y2.png - ... + res/ + cursors/ + arrowx2y2.png + ... + cursors-2x/ + arrowx2y2.png + ... Root-level split makes it easy to see which scale factors exist and is subjectively aesthetically pleasing. @@ -139,24 +135,28 @@ For now, we're going with a "-2x" suffix on the file name. ### Resource loading strategy tradeoffs -- eagerly load one scale, reload at new scale on scale factor change events - - needs explicit code - - random code in LibGfx currently loads icons, and scale factor change events would be more a LibGUI level concept, not clear how to plumb the event to there - + memory efficient -- only have one copy of each resource in memory - + easy to understand: Bitmap stays Bitmap, Font stays Font, no need for collections +- eagerly load one scale, reload at new scale on scale factor change events -- have BitmapCollection that stores high-res and low-res path and load lazily when needed - - need to do synchronous disk access at first paint on UI thread - - or load compressed data at each scale eagerly and decompress lazily. still a blocking decode on UI thread then, and needs more memory -- 2x compressed resources in memory even if they might never be needed - + puts complexity in framework, app doesn't have to care - + can transparently paint UI at both 1x and 2x into different backbuffers (eg for multiple screens that have different scale factors) + - needs explicit code + - random code in LibGfx currently loads icons, and scale factor change events would be more a LibGUI level concept, not clear how to plumb the event to there -- eagerly load both and use the right one at paint time - - similar to GUI::Icon - - 400% memory overhead in 1x mode (but most icons are small) - + conceptually easy to understand, but still need some collection class - + puts (less) complexity in framework, app doesn't have to care - + can transparently paint UI at both 1x and 2x into different backbuffers (eg for multiple screens that have different scale factors) + * memory efficient -- only have one copy of each resource in memory + * easy to understand: Bitmap stays Bitmap, Font stays Font, no need for collections + +- have BitmapCollection that stores high-res and low-res path and load lazily when needed + + - need to do synchronous disk access at first paint on UI thread + - or load compressed data at each scale eagerly and decompress lazily. still a blocking decode on UI thread then, and needs more memory -- 2x compressed resources in memory even if they might never be needed + + * puts complexity in framework, app doesn't have to care + * can transparently paint UI at both 1x and 2x into different backbuffers (eg for multiple screens that have different scale factors) + +- eagerly load both and use the right one at paint time + - similar to GUI::Icon + - 400% memory overhead in 1x mode (but most icons are small) + * conceptually easy to understand, but still need some collection class + * puts (less) complexity in framework, app doesn't have to care + * can transparently paint UI at both 1x and 2x into different backbuffers (eg for multiple screens that have different scale factors) This isn't figured out yet, for now we're doing the first approach in select places in the window server. @@ -178,8 +178,7 @@ Going forward: FIXME (depends on loading strategy decision a bit?) -Implementation plan -------------------- +## Implementation plan The plan is to have all applications use highdpi backbuffers eventually. It'll take some time to get there though, so here's a plan for getting there incrementally. diff --git a/Documentation/HumanInterfaceGuidelines/Text.md b/Documentation/HumanInterfaceGuidelines/Text.md index 5592317ff5f..68cc1654df1 100644 --- a/Documentation/HumanInterfaceGuidelines/Text.md +++ b/Documentation/HumanInterfaceGuidelines/Text.md @@ -4,32 +4,33 @@ SerenityOS employs two capitalization styles: -- Book title capitalization -- Sentence-style capitalization +- Book title capitalization +- Sentence-style capitalization ### Book title capitalization In this style, we capitalize the first letter of the first and last word, -as well as all words in between, *except* articles (a, an, the); +as well as all words in between, _except_ articles (a, an, the); the seven coordinating conjunctions (for, and, nor, but, or, yet, so); and prepositions with up to four letters (at, by, for, with, into, ...) #### Examples: -- Create New Layer -- Copy URL -- Move to Front -- Save and Exit -- Sort by Name + +- Create New Layer +- Copy URL +- Move to Front +- Save and Exit +- Sort by Name #### Used for: -- Button text -- Icon labels -- Menu names -- Menu items -- Tab titles -- Window titles -- Tooltips +- Button text +- Icon labels +- Menu names +- Menu items +- Tab titles +- Window titles +- Tooltips ### Sentence-style capitalization @@ -38,28 +39,29 @@ We capitalize the first letter of the first word, along with the first letter of proper names, weekdays, etc. #### Examples: -- An error occurred -- Use system defaults -- Copy the selected text -- Enable Linux compatibility hacks + +- An error occurred +- Use system defaults +- Copy the selected text +- Enable Linux compatibility hacks #### Used for: -- Check box labels -- Group box labels -- List items -- Messages (as in message boxes) -- Radio button labels -- Status bar text -- Text box labels +- Check box labels +- Group box labels +- List items +- Messages (as in message boxes) +- Radio button labels +- Status bar text +- Text box labels ## Ellipses The ellipsis, represented by a series of three periods (...), has two special functions in the interface: -- Eliding text -- Foreshadowing additional user input +- Eliding text +- Foreshadowing additional user input The first occurs programmatically, but the second requires care when setting text manually. @@ -72,6 +74,7 @@ completing the action. Ellipses should be used sparingly elsewhere to avoid confusion with elision. #### Examples: -- Save As... -- Browse... -- Insert Emoji... + +- Save As... +- Browse... +- Insert Emoji... diff --git a/Documentation/Kernel/AHCILocking.md b/Documentation/Kernel/AHCILocking.md index 53f9d68f2fc..c5e43c99d23 100644 --- a/Documentation/Kernel/AHCILocking.md +++ b/Documentation/Kernel/AHCILocking.md @@ -34,6 +34,7 @@ return true; ### Why do we need soft and hard locking in the AHCI code? First of all, the proper way of taking a `SpinLock` and `Lock` is to: + ```c++ Locker locker(m_soft_lock); ScopedSpinLock lock(m_spinlock); @@ -45,7 +46,7 @@ return true; ``` This sequence is relevant for any pattern of taking a soft and hard lock together in the kernel. -The reason for this order is that `SpinLock` will disable interrupts, while `Lock` will still allow the system to yield execution +The reason for this order is that `SpinLock` will disable interrupts, while `Lock` will still allow the system to yield execution to another thread if we can't lock the soft lock, because interrupts are not disabled. Taking a `SpinLock` and then a `Lock` is considered a bug, because we already disabled interrupts so yielding from this section is not possible anymore. We need both types of locking to implement hardware access safely. diff --git a/Documentation/Kernel/Containers.md b/Documentation/Kernel/Containers.md index a39d463bbe6..83058f3576c 100644 --- a/Documentation/Kernel/Containers.md +++ b/Documentation/Kernel/Containers.md @@ -9,9 +9,10 @@ unshared resources such as PIDs, filesystem view and hostname. ## Containers on the kernel side The kernel currently exposes 3 types of possible isolation mechanisms: -- VFS Root contexts -- Process lists -- Hostname contexts + +- VFS Root contexts +- Process lists +- Hostname contexts ### VFS Root Contexts @@ -54,10 +55,11 @@ from it. ## Kernel-Userspace interfaces There are 2 main syscalls to handle resource isolation: -- `unshare_create` which creates a new isolation mechanism and returns - an index number for a specified isolation type. -- `unshare_attach` which attach the user process based on the index number - and isolation type. + +- `unshare_create` which creates a new isolation mechanism and returns + an index number for a specified isolation type. +- `unshare_attach` which attach the user process based on the index number + and isolation type. ## Jails as a security mechanism diff --git a/Documentation/Kernel/DevelopmentGuidelines.md b/Documentation/Kernel/DevelopmentGuidelines.md index 519419fc481..9a11f452c88 100644 --- a/Documentation/Kernel/DevelopmentGuidelines.md +++ b/Documentation/Kernel/DevelopmentGuidelines.md @@ -168,6 +168,7 @@ on the user. All major numbers in the operating systems are allocated per device type (family of devices). We allocate them in `Kernel/API/MajorNumberAllocation.h`, based on this set of rules: + 1. The allocation is either for a new type of block device or character device, not both. 2. The family name string is not already taken for any block or character devices. 3. The family name string is informative and short. @@ -175,26 +176,26 @@ We allocate them in `Kernel/API/MajorNumberAllocation.h`, based on this set of r enum (either CharacterDeviceFamily or BlockDeviceNumber). 5. The family name string is written in snake_case name when inserted to the appropriate to-StringView function (`character_device_family_to_string_view` or `block_device_family_to_string_view`) with the actual allocation, for example: - ```c++ - ALWAYS_INLINE StringView character_device_family_to_string_view(CharacterDeviceFamily family) - { - switch (family) { + ```c++ + ALWAYS_INLINE StringView character_device_family_to_string_view(CharacterDeviceFamily family) + { + switch (family) { + ... + case CharacterDeviceFamily::FUSE: + return "fuse"sv; ... - case CharacterDeviceFamily::FUSE: - return "fuse"sv; - ... - } - } - ``` - Also, you should add an entry in either `s_character_device_numbers` or `s_block_device_numbers` array. - For example: - ```c++ - static constexpr CharacterDeviceFamily s_character_device_numbers[] = { - ... - CharacterDeviceFamily::FUSE, - ... - }; - ``` + } + } + ``` + Also, you should add an entry in either `s_character_device_numbers` or `s_block_device_numbers` array. + For example: + ```c++ + static constexpr CharacterDeviceFamily s_character_device_numbers[] = { + ... + CharacterDeviceFamily::FUSE, + ... + }; + ``` 6. The allocation must be inserted by keeping the ascending order of the allocated major numbers in the appropriate enum and associated to-StringView function. @@ -205,6 +206,7 @@ afterwards. To make it easier writing device drivers, when constructing an object from a `Device`-derived class, the usual pattern is to use `DeviceManagement` `try_create_device` method. For example, constructing a `VirtIOGPU3DDevice` is done this way: + ```c++ ErrorOr<NonnullLockRefPtr<VirtIOGPU3DDevice>> VirtIOGPU3DDevice::try_create(VirtIOGraphicsAdapter& adapter) { diff --git a/Documentation/Kernel/GraphicsSubsystem.md b/Documentation/Kernel/GraphicsSubsystem.md index 60b5eec038d..2685d993b88 100644 --- a/Documentation/Kernel/GraphicsSubsystem.md +++ b/Documentation/Kernel/GraphicsSubsystem.md @@ -7,14 +7,14 @@ manage all graphics devices, framebuffers, hardware 3D acceleration, memory mapp ## Responsibilities -* Provide a convenient interface to all supported video hardware in the Kernel. -* Manage 3D rendering on supported hardware. +- Provide a convenient interface to all supported video hardware in the Kernel. +- Manage 3D rendering on supported hardware. ## Current Limitations and Future features? -* No locking on who can do `mmap` on DisplayConnector devices currently, which can -lead to malicious applications "fighting" with WindowServer on what is shown to the user -from the framebuffer. +- No locking on who can do `mmap` on DisplayConnector devices currently, which can + lead to malicious applications "fighting" with WindowServer on what is shown to the user + from the framebuffer. # DisplayConnector Devices @@ -74,7 +74,7 @@ To try to cope with the dire situation, the VBE (Video BIOS extensions) standard help BIOS and operating system vendors to be able to get high resolution framebuffer from any hardware that complied to the standard. When UEFI came along, the vendors agreed to create the Graphics output protocol (known as UEFI GOP), to provide the same set of features -that VBE had, but now is usable from 64-bit kernel code as long as the kernel didn't shutdown +that VBE had, but now is usable from 64-bit kernel code as long as the kernel didn't shutdown the UEFI services (which it really should do) after completing the boot process. ## Then how does it all apply to the subsystem? @@ -104,15 +104,15 @@ device, while keeping the control to the Kernel to decide who accesses the actua at a given time. This works by working with the following assumptions: 1. Current usage of `mmap` is only for direct framebuffer manipulation. This means -that if we add support for batch buffers or other objects that should reside in VRAM, this trick -can lead to catastrophic incidents with the underlying hardware. This happens to be this way, due to -the fact that we essentially can take VRAM access from the WindowServer at anytime we want, -without the WindowServer being aware of this so it can still function in the background. + that if we add support for batch buffers or other objects that should reside in VRAM, this trick + can lead to catastrophic incidents with the underlying hardware. This happens to be this way, due to + the fact that we essentially can take VRAM access from the WindowServer at anytime we want, + without the WindowServer being aware of this so it can still function in the background. 2. We need to know the maximum dimensions of the framebuffers when initializing the device -and creating the DisplayConnector device at runtime. This happens because we map all the possible -pages of VRAM framebuffer at that time, and also reserve the same amount of pages in usable -physical memory space, so we could reserve the contents of VRAM between the switch -from graphics mode to console mode and vice-versa. + and creating the DisplayConnector device at runtime. This happens because we map all the possible + pages of VRAM framebuffer at that time, and also reserve the same amount of pages in usable + physical memory space, so we could reserve the contents of VRAM between the switch + from graphics mode to console mode and vice-versa. The actual implementation is quite simple, yet powerful enough to let everyone live comfortably - each DisplayConnector device is backed by a special VMObject (VMObject is @@ -120,7 +120,7 @@ the base class for managing virtual memory scenarios easily) that is created whe DisplayConnector device is initialized - we need to find the physical address of the start of the framebuffer and the maximum resource size (this is where PCI BARs play their role, as we can determine with them the physical address by reading their values and also -the maximum resource size, by doing a very simple write 1s-and-read trick that was introduced +the maximum resource size, by doing a very simple write 1s-and-read trick that was introduced with the PCI bus when it was created). Then when the object is created, the code ensures we reserve for later usage the same amount of pages somewhere else to ensure we preserve the contents of VRAM between the switch from console and graphics mode and vice-versa. @@ -132,21 +132,21 @@ to the framebuffer in the background. ## Do you plan supporting old VGA adapters? Given the nature of the user experience SerenityOS strives to deliver to the users, -a core requirement from the first day of this project was to only support 32 bit-per-pixel -(also known as True-color framebuffer) hardware framebuffers. We do support hardware -framebuffers that neglect the alpha-channel (essentially it's a 24 bit-per-pixel), -as long as each pixel is aligned to 4 bytes. The QEMU std-vga (bochs-display with +a core requirement from the first day of this project was to only support 32 bit-per-pixel +(also known as True-color framebuffer) hardware framebuffers. We do support hardware +framebuffers that neglect the alpha-channel (essentially it's a 24 bit-per-pixel), +as long as each pixel is aligned to 4 bytes. The QEMU std-vga (bochs-display with VGA capabilities) device was chosen as the first device to be supported in the project, and that was an excellent choice for that time to put up with the said requirement. This hard requirement is due to the fact that supporting anything besides True-color -framebuffers is a *waste of time* for a new modern kernel. Not only that, but relying -on VGA with modern monitors is essentially settling for blurry, badly-shaped graphics +framebuffers is a _waste of time_ for a new modern kernel. Not only that, but relying +on VGA with modern monitors is essentially settling for blurry, badly-shaped graphics on a computer monitor, due to unoptimized resolution scaling with modern screen ratios. Old VGA adapters are certainly not capable of using high resolution framebuffers when operating in pure native VGA mode (i.e. not operating in an extension mode -of the video adapter), therefore, if the Kernel cannot find a suitable framebuffer +of the video adapter), therefore, if the Kernel cannot find a suitable framebuffer to work with or a video adapter it has a driver for, then the last resort is to use the old VGA text mode console. Therefore, the SerenityOS kernel will probably never support pure VGA functionality. That technology was good for operating systems in the 90s, but is not usable anymore. @@ -158,6 +158,7 @@ helps keeping the Graphics subsystem lean and flexible to future changes. As for using Video BIOS extensions - this requires us to be able to call to BIOS 16-bit real mode code. The solutions for these are: + 1. Drop to real mode, invoke the BIOS interrupt and return to our kernel. 2. Writing a Real-Mode 16-bit emulator, either in Kernel space or userspace. 3. Use Intel VT-x extensions to simulate a processor running in Real mode. @@ -169,27 +170,29 @@ take a not negligible amount of effort to get something usable and correct. Usin such as Intel VT-x or the v8086 mode are almost equally equivalent to writing an emulator. We will probably never support using the Video BIOS extensions because of these reasons: + 1. Major part of this project is to maximize usability and fun on what we do, and turning into legacy-cruft to -temporarily solve a solution is not the right thing to do. + temporarily solve a solution is not the right thing to do. 2. VBE is not usable on machines that lack support of BIOS. As of 2022, this increasingly becomes a problem -because many PC vendors dropped support for BIOS (known as CSM [Compatibility Support Module] in UEFI terms). + because many PC vendors dropped support for BIOS (known as CSM [Compatibility Support Module] in UEFI terms). 3. VBE is limited to whatever the vendor decided to hardcode in the OptionROM of the video adapter, which means -it can limit us to a small set of resolutions and bits-per-pixel settings, -some of these settings are not convenient for us, nor suitable for our needs. + it can limit us to a small set of resolutions and bits-per-pixel settings, + some of these settings are not convenient for us, nor suitable for our needs. 4. VBE lacks the support of detecting if the screen actually supports the resolution settings, -which means that the operating system has to use other methods to determine if screen output is -working properly (e.g. waiting for a couple of seconds for user confirmation on the selected settings). -This is because VBE lacks support of getting the screen EDID because most of the time, -the EDID resides in a ROM in the computer screen, which is inaccessible without using specific -methods to extract it (via the Display Data Channel), which are not encoded or implemented in -the PCI OptionROM of the device. -This is in contrast to native drivers which are able to do this, and VGA, that never relied on -such methods and instead relied on all video adapters and computer screen to use an well-known -specification-defined display modes. + which means that the operating system has to use other methods to determine if screen output is + working properly (e.g. waiting for a couple of seconds for user confirmation on the selected settings). + This is because VBE lacks support of getting the screen EDID because most of the time, + the EDID resides in a ROM in the computer screen, which is inaccessible without using specific + methods to extract it (via the Display Data Channel), which are not encoded or implemented in + the PCI OptionROM of the device. + This is in contrast to native drivers which are able to do this, and VGA, that never relied on + such methods and instead relied on all video adapters and computer screen to use an well-known + specification-defined display modes. ## What are the native drivers that are included in the kernel? what type of configurations are supported? The kernel can be configured to operate in the following conditions: + 1. Fully-enable the graphics subsystem, initialize every device being supported. 2. Only use the pre-initialized framebuffer from the bootloader, don't initialize anything else. 3. Don't use any framebuffer, don't initialize any device. diff --git a/Documentation/Kernel/IOWindow.md b/Documentation/Kernel/IOWindow.md index 8be29b702cd..dfab43251dd 100644 --- a/Documentation/Kernel/IOWindow.md +++ b/Documentation/Kernel/IOWindow.md @@ -13,7 +13,6 @@ IOAddress io(0x3f0) u8 ide_status = io.offset(0).in<u8>() ``` - ### Memory-mapped IO Memory mapped IO is a platform-agnostic method to access hardware registers. It uses a @@ -42,13 +41,14 @@ mapped registers as being defined in the SATA AHCI HBA specification. The general rule in kernel driver programming is to know that there are only two valid cases on whether to use the `IOWindow` structure or not: + 1. The device is known to either use the IO space, memory space or both, taking into -consideration that variants of the device can disable either of the options. In this case, -we need to use the `IOWindow` structure as it will help us to correctly use the IO window -in either case. + consideration that variants of the device can disable either of the options. In this case, + we need to use the `IOWindow` structure as it will help us to correctly use the IO window + in either case. 2. The device is known to use only the memory space, therefore we can ignore the `IOWindow` -structure and instead use the `Memory::TypedMapping` structure to help navigating in -the memory-mapped registers of the device. + structure and instead use the `Memory::TypedMapping` structure to help navigating in + the memory-mapped registers of the device. # A note about 64 bit access for memory mapped IO diff --git a/Documentation/Kernel/ProcFSIndexing.md b/Documentation/Kernel/ProcFSIndexing.md index 9723a70910b..e57caa4aba5 100644 --- a/Documentation/Kernel/ProcFSIndexing.md +++ b/Documentation/Kernel/ProcFSIndexing.md @@ -23,18 +23,19 @@ effects of the disadvantages of each design. ### The layout of the segmented index -Since it was decided that heap allocations for ProcFS are *mostly* bad, the new +Since it was decided that heap allocations for ProcFS are _mostly_ bad, the new design layout tries to achieve most of the principle of "Don't allocate anything until actually needed". For that to happen, `InodeIndex` (u64 value) is split into 3 Segments: -- The primary segment: value 0 is reserved for all non-PID inodes in the procfs. -All values from 1 to 0xFFFFFFF are valid PID indices, which represents all PIDs from 0 to 0xFFFFFFE -- The Sub-directory segment: value 0 is reserved for parent PID directory. All other values are -available for usage of sub-directories in the PID directory. +- The primary segment: value 0 is reserved for all non-PID inodes in the procfs. + All values from 1 to 0xFFFFFFF are valid PID indices, which represents all PIDs from 0 to 0xFFFFFFE -- The property segment: value 0 is reserved for parent PID directory. All other values are -available for usage of components in the PID directory or in sub-directories of the PID directory. +- The Sub-directory segment: value 0 is reserved for parent PID directory. All other values are + available for usage of sub-directories in the PID directory. + +- The property segment: value 0 is reserved for parent PID directory. All other values are + available for usage of components in the PID directory or in sub-directories of the PID directory. So, the final layout of the 64 bit index is: @@ -55,17 +56,16 @@ to allocate global objects, so it's somewhat a compromise between two conflictin To do that we need to ensure that: 1. If the primary segment value equals to 0, then the sub-directory and property segmentation -is not applied, but a sequential indexing is determined instead. This is needed so ProcFS can still -use global components that were pre-allocated beforehand. This means that there might be up to -68719476735 global components (including global sub-directories objects) in the ProcFS. -Otherwise, for every primary segment value > 0, then the sub-directory and property segmentation -is applied. This means that there might be up to 65534 sub-directories in a PID directory, and -up to 1048575 (1048574 for PID directory) properties (objects) in each sub-directory. - -2. If the primary segment value equals to 0, then value 0 in both artificial sub-directory -and property segments represents the root ProcFS folder. -Otherwise, for every primary segment value > 0, value 0 in both sub-directory and -property segments are reserved to represent the root PID directory. -Please note that if the sub-directory segment > 0, and property segment = 0 is a valid -index, and represents a valid property object in that sub-directory. + is not applied, but a sequential indexing is determined instead. This is needed so ProcFS can still + use global components that were pre-allocated beforehand. This means that there might be up to + 68719476735 global components (including global sub-directories objects) in the ProcFS. + Otherwise, for every primary segment value > 0, then the sub-directory and property segmentation + is applied. This means that there might be up to 65534 sub-directories in a PID directory, and + up to 1048575 (1048574 for PID directory) properties (objects) in each sub-directory. +2. If the primary segment value equals to 0, then value 0 in both artificial sub-directory + and property segments represents the root ProcFS folder. + Otherwise, for every primary segment value > 0, value 0 in both sub-directory and + property segments are reserved to represent the root PID directory. + Please note that if the sub-directory segment > 0, and property segment = 0 is a valid + index, and represents a valid property object in that sub-directory. diff --git a/Documentation/Kernel/RAMFS.md b/Documentation/Kernel/RAMFS.md index 44c6e1bd2cb..134d7207b39 100644 --- a/Documentation/Kernel/RAMFS.md +++ b/Documentation/Kernel/RAMFS.md @@ -29,7 +29,7 @@ Other programs rely on `/tmp` for placing their temporary files to properly func To understand why `RAMFS` works reliably when mounted on `/dev`, we must understand first what we did in the past and how `RAMFS` solves many of the issues with the previous design. -At first, we didn't have any special filesystem mounted in `/dev` as the image build +At first, we didn't have any special filesystem mounted in `/dev` as the image build script generated all the required device nodes in `/dev`. This was quite sufficient in the early days of the project, where hardware support was extremely limited and of course hotplugging any kind of hardware was not even a consideration. diff --git a/Documentation/NvimConfiguration.md b/Documentation/NvimConfiguration.md index 8084465694d..cf4858ea889 100644 --- a/Documentation/NvimConfiguration.md +++ b/Documentation/NvimConfiguration.md @@ -41,7 +41,7 @@ This will install a separate version of clangd just for neovim. Use the following settings to ensure that coc-clangd works out of the box. > **Note**: You might want to adjust the `clangd.fallbackFlags` depending on your build -system and customize the `inlayHints.sep` based on your preference. +> system and customize the `inlayHints.sep` based on your preference. ```json { @@ -58,22 +58,27 @@ To change the coc-settings.json go to the file `~/.config/nvim/coc-settings.json or type `:CocConfig` in the command line. > **Note**: In case you already had another c++ language server configured in the -`coc-settings.json` you might want to nuke it first and -work towards your desired config by adding the other parts back in to avoid -conflicts. +> `coc-settings.json` you might want to nuke it first and +> work towards your desired config by adding the other parts back in to avoid +> conflicts. > **Note**: If you have configured `clangd` as a languageServer in -`coc-settings.json`, you should remove it to avoid running clangd twice! +> `coc-settings.json`, you should remove it to avoid running clangd twice! > **Note**: `clangd.inlayHints.sep` breaks on `clangd 15.0.6`. # Formatting + For code formatting the formatter plugin can be used. + ```vim Plug 'mhartington/formatter.nvim' ``` + ### Configuration + To use the formatter plugin one needs to opt-in to specific formatters. An example lua configuration which uses clang-format for cpp files: + ```lua require("formatter").setup{ filetype = { @@ -179,7 +184,7 @@ nmap <silent>gs :CocCommand clangd.switchSourceHeader vsplit<CR> # Configure .clangd > **Note**: Every time a new source is added or the compilation commands get adjusted -(through CMake) you need to rerun `./Meta/serenity.sh rebuild`. +> (through CMake) you need to rerun `./Meta/serenity.sh rebuild`. Link `ln -s /path/to/serenity/Build/x86_64/compile_commands.json /path/to/serenity/compile_commands.json`. @@ -188,4 +193,4 @@ with your SerenityOS directory) with content of the clangd section in the [VSCodeConfiguration.md](./VSCodeConfiguration.md). > **Note**: You can add a `Remove` part, where you can remove unwanted flags -such as those that aren't supported by the current version of clang. +> such as those that aren't supported by the current version of clang. diff --git a/Documentation/Patterns.md b/Documentation/Patterns.md index a28319e25df..bd82fedc98c 100644 --- a/Documentation/Patterns.md +++ b/Documentation/Patterns.md @@ -4,17 +4,17 @@ Over time numerous reoccurring patterns have emerged from or were adopted by the serenity code base. This document aims to track and describe them, so they -can be propagated further and the code base can be kept consistent. +can be propagated further and the code base can be kept consistent. ## `TRY(...)` Error Handling The `TRY(..)` macro is used for error propagation in the serenity code base. The goal being to reduce the amount of boiler plate error code required to -properly handle and propagate errors throughout the code base. +properly handle and propagate errors throughout the code base. Any code surrounded by `TRY(..)` will attempt to be executed, and any error will immediately be returned from the function. If no error occurs then the -result of the contents of the TRY will be the result of the macro's execution. +result of the contents of the TRY will be the result of the macro's execution. ### Examples: @@ -164,7 +164,7 @@ Instead, `serenity_main(..)` is defined like this: ErrorOr<int> serenity_main(Main::Arguments arguments) { - return 0; + return 0; } ``` @@ -226,7 +226,7 @@ It's a universal pattern to use `static_assert` to validate the size of a type matches the author's expectations. Unfortunately when these assertions fail they don't give you the values that actually caused the failure. This forces one to go investigate by printing out the size, or checking it in a -debugger, etc. +debugger, etc. For this reason `AK::AssertSize` was added. It exploits the fact that the compiler will emit template argument values for compiler errors to provide @@ -256,10 +256,11 @@ static_assert(AssertSize<Empty, 1>()); ``` This allows `AK::StringView` to be constructed from string literals with no runtime -cost to find the string length, and the data the `AK::StringView` points to will +cost to find the string length, and the data the `AK::StringView` points to will reside in the data section of the binary. Example Usage: + ```cpp #include <AK/String.h> #include <AK/StringView.h> @@ -278,7 +279,7 @@ TEST_CASE(string_view_literal_operator) ## Source Location C++20 added std::source_location, which lets you capture the -callers __FILE__ / __LINE__ / __FUNCTION__ etc as a default +callers **FILE** / **LINE** / **FUNCTION** etc as a default argument to functions. See: https://en.cppreference.com/w/cpp/utility/source_location @@ -292,6 +293,7 @@ to any function, using `AK::SourceLocation::current()` to initialize the default argument. Example Usage: + ```cpp #include <AK/SourceLocation.h> #include <AK/StringView.h> @@ -308,7 +310,7 @@ int main(int, char**) ``` If you only want to only capture `AK::SourceLocation` data with a certain debug macro enabled, avoid -adding `#ifdef`'s to all functions which have the `AK::SourceLocation` argument. Since SourceLocation +adding `#ifdef`'s to all functions which have the `AK::SourceLocation` argument. Since SourceLocation is just a simple struct, you can just declare an empty class which can be optimized away by the compiler, and alias both to the same name. @@ -336,9 +338,9 @@ private: There are four "contiguous list" / array-like types, including C-style arrays themselves. They share a lot of their API, but their use cases are all slightly different, mostly relating to how they allocate their data. -Note that `Span<type>` differs from all of these types in that it provides a *view* on data owned by somebody else. The four types mentioned above all own their data, but they can provide `Span`'s which view all or part of their data. For APIs that aren't specific to the kind of list and don't need to handle resizing in any way, `Span` is a good choice. +Note that `Span<type>` differs from all of these types in that it provides a _view_ on data owned by somebody else. The four types mentioned above all own their data, but they can provide `Span`'s which view all or part of their data. For APIs that aren't specific to the kind of list and don't need to handle resizing in any way, `Span` is a good choice. -* C-style arrays are generally discouraged (and this also holds for pointer+size-style arrays when passing them around). They are only used for the implementation of other collections or in specific circumstances. -* `Array` is a thin wrapper around C-style arrays similar to `std::array`, where the template arguments include the size of the array. It allocates its data inline, just as arrays do, and never does any dynamic allocations. -* `Vector` is similar to `std::vector` and represents a dynamic resizable array. For most basic use cases of lists, this is the go-to collection. It has an optional inline capacity (the second template argument) which will allocate inline as the name suggests, but this is not always used. If the contents outgrow the inline capacity, Vector will automatically switch to the standard out-of-line storage. This is allocated on the heap, and the space is automatically resized and moved when more (or less) space is needed. -* `FixedArray` is essentially a runtime-sized `Array`. It can't resize like `Vector`, but it's ideal for circumstances where the size is not known at compile time but doesn't need to change once the collection is initialized. `FixedArray` guarantees to not allocate or deallocate except for its constructor and destructor. +- C-style arrays are generally discouraged (and this also holds for pointer+size-style arrays when passing them around). They are only used for the implementation of other collections or in specific circumstances. +- `Array` is a thin wrapper around C-style arrays similar to `std::array`, where the template arguments include the size of the array. It allocates its data inline, just as arrays do, and never does any dynamic allocations. +- `Vector` is similar to `std::vector` and represents a dynamic resizable array. For most basic use cases of lists, this is the go-to collection. It has an optional inline capacity (the second template argument) which will allocate inline as the name suggests, but this is not always used. If the contents outgrow the inline capacity, Vector will automatically switch to the standard out-of-line storage. This is allocated on the heap, and the space is automatically resized and moved when more (or less) space is needed. +- `FixedArray` is essentially a runtime-sized `Array`. It can't resize like `Vector`, but it's ideal for circumstances where the size is not known at compile time but doesn't need to change once the collection is initialized. `FixedArray` guarantees to not allocate or deallocate except for its constructor and destructor. diff --git a/Documentation/QtCreatorConfiguration.md b/Documentation/QtCreatorConfiguration.md index 7a6c72f10ac..d5d0dd41cca 100644 --- a/Documentation/QtCreatorConfiguration.md +++ b/Documentation/QtCreatorConfiguration.md @@ -4,16 +4,17 @@ First, make sure you have a working toolchain and can build and run SerenityOS. Go [here](BuildInstructions.md) for instructions for setting that up. -* Install [Qt Creator](https://www.qt.io/offline-installers). You don't need the entire Qt setup, just click 'Qt Creator' on the left side, and install that. -* Open Qt Creator, select `File -> New File or Project...` -* Select `Import Existing Project` -* Give it a name (some tools assume lower-case `serenity`), and navigate to the root of your SerenityOS project checkout. Click Next. -* Wait for the file list to generate. This can take a minute or two! -* Ignore the file list, we will overwrite it later. Click Next. -* Set `Add to version control` to `<None>`. Click Finish. -* In your shell, go to your SerenityOS project directory, and invoke the `Meta/refresh-serenity-qtcreator.sh` script to regenerate the `serenity.files` file. You will also have to do this every time you delete or add a new file to the project. -* Edit the `serenity.config` file (In Qt Creator, hit ^K or CMD+K on a Mac to open the search dialog, type the name of the file and hit return to open it) -* Add the following `#define`s to the file: +- Install [Qt Creator](https://www.qt.io/offline-installers). You don't need the entire Qt setup, just click 'Qt Creator' on the left side, and install that. +- Open Qt Creator, select `File -> New File or Project...` +- Select `Import Existing Project` +- Give it a name (some tools assume lower-case `serenity`), and navigate to the root of your SerenityOS project checkout. Click Next. +- Wait for the file list to generate. This can take a minute or two! +- Ignore the file list, we will overwrite it later. Click Next. +- Set `Add to version control` to `<None>`. Click Finish. +- In your shell, go to your SerenityOS project directory, and invoke the `Meta/refresh-serenity-qtcreator.sh` script to regenerate the `serenity.files` file. You will also have to do this every time you delete or add a new file to the project. +- Edit the `serenity.config` file (In Qt Creator, hit ^K or CMD+K on a Mac to open the search dialog, type the name of the file and hit return to open it) +- Add the following `#define`s to the file: + ``` //#define KERNEL @@ -24,9 +25,11 @@ First, make sure you have a working toolchain and can build and run SerenityOS. #define SANITIZE_PTRS 1 #define __SSE__ ``` + If you're working on the Kernel, just uncomment `#define KERNEL`. -* Edit the `serenity.cxxflags` file to say `-std=c++23 -fsigned-char -fconcepts -fno-exceptions -fno-semantic-interposition -fPIC` -* Edit the `serenity.includes` file to list the following lines: + +- Edit the `serenity.cxxflags` file to say `-std=c++23 -fsigned-char -fconcepts -fno-exceptions -fno-semantic-interposition -fPIC` +- Edit the `serenity.includes` file to list the following lines: ``` ./ Userland/ @@ -50,16 +53,16 @@ Qt Creator should be set up correctly now, go ahead and explore the project and You can use `clang-format` to help you with the [style guide](CodingStyle.md). Before you proceed, check that you're actually using clang-format version 18, as some OSes will ship older clang-format versions by default. -- In QtCreator, go to "Help > About Plugins…" -- Find the `Beautifier (experimental)` row (for example, by typing `beau` into the search) -- Put a checkmark into the box -- Restart QtCreator if it asks you -- In QtCreator, go to "Tools > Options…" -- Type "beau" in the search box, go to "Beautifier > Clang Format" -- Select the "customized" style, click "edit" -- Paste the entire content of the file `.clang-format` into the "value" box, and click "OK" -- In the "Beautifier > General" tab, check "Enable auto format on file save" -- Select the tool "ClangFormat" if not already selected, and click "OK" +- In QtCreator, go to "Help > About Plugins…" +- Find the `Beautifier (experimental)` row (for example, by typing `beau` into the search) +- Put a checkmark into the box +- Restart QtCreator if it asks you +- In QtCreator, go to "Tools > Options…" +- Type "beau" in the search box, go to "Beautifier > Clang Format" +- Select the "customized" style, click "edit" +- Paste the entire content of the file `.clang-format` into the "value" box, and click "OK" +- In the "Beautifier > General" tab, check "Enable auto format on file save" +- Select the tool "ClangFormat" if not already selected, and click "OK" Note that not the entire project is clang-format-clean (yet), so sometimes you will see large diffs. Use your own judgement whether you want to include such changes. Generally speaking, if it's a few lines then it's a good idea; if it's the entire file then maybe there's a better way to do it, like doing a separate commit, or just ignoring the clang-format changes. @@ -67,12 +70,13 @@ Use your own judgement whether you want to include such changes. Generally speak You may want to read up what `git add -p` does (or `git checkout -p`, to undo). QtCreator tends to interpret IPC definitions as C++ headers, and then tries to format them. This is not useful. One way to avoid that is telling QtCreator that IPC definitions are not C++ headers. -- In QtCreator, go to "Tools > Options…" -- Type "beau" in the search box, go to "Environment > MIME Types" -- In the little search box, type "plain", and select "text/plain" -- In the "details" section, you should now see the list of Patterns, something like `*.txt;*.asc;*,v`. Extend it in the following way: `*.txt;*.asc;*,v;*.ipc;*.gml` -- Click "OK" to close the dialog. -- Maybe you need to close and open again the IPC files. You can check what QtCreator is doing by right-clicking the filename in the editor tab, and clicking "Properties...". In the third line, you should see `MIME type: text/plain`. + +- In QtCreator, go to "Tools > Options…" +- Type "beau" in the search box, go to "Environment > MIME Types" +- In the little search box, type "plain", and select "text/plain" +- In the "details" section, you should now see the list of Patterns, something like `*.txt;*.asc;*,v`. Extend it in the following way: `*.txt;*.asc;*,v;*.ipc;*.gml` +- Click "OK" to close the dialog. +- Maybe you need to close and open again the IPC files. You can check what QtCreator is doing by right-clicking the filename in the editor tab, and clicking "Properties...". In the third line, you should see `MIME type: text/plain`. ## License template diff --git a/Documentation/README.md b/Documentation/README.md index 924b01d8032..8c03b8713f3 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -5,72 +5,82 @@ Serenity development moves quickly, so some of these might be out of date. Pleas A list of useful pages across the web can be found on [the link list](Links.md). ## Building and Running -* [Build Instructions](BuildInstructions.md) -* [Advanced Build Instructions](AdvancedBuildInstructions.md) -* [Troubleshooting](Troubleshooting.md) -* [Running in VirtualBox](VirtualBox.md) -* [Running in VMware](VMware.md) -* [Running Tests](RunningTests.md) -* [Setting Up Self-Hosted Runners](SelfHostedRunners.md) -* [Profiling the Build](BuildProfilingInstructions.md) -* [Spice Integration](SpiceIntegration.md) + +- [Build Instructions](BuildInstructions.md) +- [Advanced Build Instructions](AdvancedBuildInstructions.md) +- [Troubleshooting](Troubleshooting.md) +- [Running in VirtualBox](VirtualBox.md) +- [Running in VMware](VMware.md) +- [Running Tests](RunningTests.md) +- [Setting Up Self-Hosted Runners](SelfHostedRunners.md) +- [Profiling the Build](BuildProfilingInstructions.md) +- [Spice Integration](SpiceIntegration.md) ### OS-specific + Make sure to read the basic [Build Instructions](BuildInstructions.md) first. -* [Building on Windows](BuildInstructionsWindows.md) -* [Building on macOS](BuildInstructionsMacOS.md) -* [Building on Linux](BuildInstructionsOther.md) + +- [Building on Windows](BuildInstructionsWindows.md) +- [Building on macOS](BuildInstructionsMacOS.md) +- [Building on Linux](BuildInstructionsOther.md) ### Running on Hardware -* [Bare Metal Installation](BareMetalInstallation.md) -* [Running On Raspberry Pi](RunningOnRaspberryPi.md) -* [Known Hardware Compatibility](HardwareCompatibility.md) + +- [Bare Metal Installation](BareMetalInstallation.md) +- [Running On Raspberry Pi](RunningOnRaspberryPi.md) +- [Known Hardware Compatibility](HardwareCompatibility.md) ## Configuring Editors -* [CLion](CLionConfiguration.md) -* [Emacs](EmacsConfiguration.md) -* [Helix](HelixConfiguration.md) -* [NVim](NvimConfiguration.md) -* [Qt Creator](QtCreatorConfiguration.md) -* [Vim](VimConfiguration.md) -* [VS Code](VSCodeConfiguration.md) + +- [CLion](CLionConfiguration.md) +- [Emacs](EmacsConfiguration.md) +- [Helix](HelixConfiguration.md) +- [NVim](NvimConfiguration.md) +- [Qt Creator](QtCreatorConfiguration.md) +- [Vim](VimConfiguration.md) +- [VS Code](VSCodeConfiguration.md) ## Development -* [How to Contribute](../CONTRIBUTING.md) -* [Coding Style](CodingStyle.md) -* [Common Patterns](Patterns.md) -* [Guidelines for Text in UI](HumanInterfaceGuidelines/Text.md) -* [Guidelines for writing manual pages](WritingManPages.md) -* [EventLoop](EventLoop.md) -* [High DPI Support](HighDPI.md) -* [Smart Pointers](SmartPointers.md) -* [String Formatting](StringFormatting.md) -* [How to Transfer Files Out of Serenity](TransferringFiles.md) + +- [How to Contribute](../CONTRIBUTING.md) +- [Coding Style](CodingStyle.md) +- [Common Patterns](Patterns.md) +- [Guidelines for Text in UI](HumanInterfaceGuidelines/Text.md) +- [Guidelines for writing manual pages](WritingManPages.md) +- [EventLoop](EventLoop.md) +- [High DPI Support](HighDPI.md) +- [Smart Pointers](SmartPointers.md) +- [String Formatting](StringFormatting.md) +- [How to Transfer Files Out of Serenity](TransferringFiles.md) ### File and Data Formats -* [Application Files (.af)](../Base/usr/share/man/man5/af.md) -* [Bitmap Fonts (.font)](../Base/usr/share/man/man5/font.md) -* [Clipboard data](../Base/usr/share/man/man5/clipboard.md) -* [Drag-and-drop data](../Base/usr/share/man/man5/drag-and-drop.md) -* [GUI Markup Language (.gml)](../Base/usr/share/man/man5/GML.md) -* [HackStudio Post-Create Scripts (.postcreate)](../Base/usr/share/man/man5/postcreate.md) -* [Inter-Process Communication protocol (.ipc)](../Base/usr/share/man/man4/ipc.md) + +- [Application Files (.af)](../Base/usr/share/man/man5/af.md) +- [Bitmap Fonts (.font)](../Base/usr/share/man/man5/font.md) +- [Clipboard data](../Base/usr/share/man/man5/clipboard.md) +- [Drag-and-drop data](../Base/usr/share/man/man5/drag-and-drop.md) +- [GUI Markup Language (.gml)](../Base/usr/share/man/man5/GML.md) +- [HackStudio Post-Create Scripts (.postcreate)](../Base/usr/share/man/man5/postcreate.md) +- [Inter-Process Communication protocol (.ipc)](../Base/usr/share/man/man4/ipc.md) ## Browser/LibWeb -* [Ladybird Browser Build Instructions](BuildInstructionsLadybird.md) -* [General Architecture](Browser/ProcessArchitecture.md) -* [LibWeb: From Loading to Painting](Browser/LibWebFromLoadingToPainting.md) -* [How to Add an IDL File](Browser/AddNewIDLFile.md) -* [LibWeb Code Style & Patterns](Browser/Patterns.md) -* [CSS Generated Files](Browser/CSSGeneratedFiles.md) + +- [Ladybird Browser Build Instructions](BuildInstructionsLadybird.md) +- [General Architecture](Browser/ProcessArchitecture.md) +- [LibWeb: From Loading to Painting](Browser/LibWebFromLoadingToPainting.md) +- [How to Add an IDL File](Browser/AddNewIDLFile.md) +- [LibWeb Code Style & Patterns](Browser/Patterns.md) +- [CSS Generated Files](Browser/CSSGeneratedFiles.md) ## Kernel -* [AHCI Locking](Kernel/AHCILocking.md) -* [ProcFS Indexing](Kernel/ProcFSIndexing.md) -* [RAMFS](Kernel/RAMFS.md) -* [IOWindow](Kernel/IOWindow.md) -* [Graphics Subsystem](Kernel/GraphicsSubsystem.md) -* [Kernel Development Patterns & Guidelines](Kernel/DevelopmentGuidelines.md) + +- [AHCI Locking](Kernel/AHCILocking.md) +- [ProcFS Indexing](Kernel/ProcFSIndexing.md) +- [RAMFS](Kernel/RAMFS.md) +- [IOWindow](Kernel/IOWindow.md) +- [Graphics Subsystem](Kernel/GraphicsSubsystem.md) +- [Kernel Development Patterns & Guidelines](Kernel/DevelopmentGuidelines.md) ## Applications + Documentation for SerenityOS applications and utilities can be found in [the man pages](https://man.serenityos.org/). diff --git a/Documentation/SelfHostedRunners.md b/Documentation/SelfHostedRunners.md index 98b4bd5701c..6fb595c0e50 100644 --- a/Documentation/SelfHostedRunners.md +++ b/Documentation/SelfHostedRunners.md @@ -2,21 +2,24 @@ ## Requirements -Since these self hosted-runners are supposed to be a more performant alternative to the GitHub-provided runners, the bare minimum requirements are GitHub's own Linux runner [hardware specification](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources) as well as guaranteed uptime. +Since these self hosted-runners are supposed to be a more performant alternative to the GitHub-provided runners, the bare minimum requirements are GitHub's own Linux runner [hardware specification](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources) as well as guaranteed uptime. As for recommended requirements, listed below are the specifications of the current SerenityOS runners, roughly matching these would eventually make running performance-regression related tests on these easier. (But this is not a hard requirement, as GitHub offers the ability to selectively choose which self-hosted runners run which workflow) #### IdanHo runner: - - Ryzen 5 3600 - 12 cores w/ KVM support - - 64GB of RAM - - 512GB of SSD space -###### This runner can be split into 2 runners with half the cores/RAM/space if needed. + +- Ryzen 5 3600 - 12 cores w/ KVM support +- 64GB of RAM +- 512GB of SSD space + +###### This runner can be split into 2 runners with half the cores/RAM/space if needed. ## Setup These instructions assume the OS installed is Ubuntu 22.04 (Jammy), so they might not be compatible with other Linux flavours. ### Install base dependencies + ```shell sudo add-apt-repository ppa:canonical-server/server-backports wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add - @@ -24,52 +27,77 @@ sudo add-apt-repository 'deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-16 apt update apt install git build-essential make cmake clang-format-16 gcc-13 g++-13 libstdc++-13-dev libgmp-dev ccache libmpfr-dev libmpc-dev ninja-build e2fsprogs qemu-utils qemu-system-i386 wabt ``` + ### Force usage of GCC 13 + ```shell update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100 --slave /usr/bin/g++ g++ /usr/bin/g++-13 ``` + ### Create a new user account named 'runner' + ```shell adduser runner ``` + ### Give it password-less sudo capabilities by adding the following line to /etc/sudoers: + ```shell runner ALL=(ALL) NOPASSWD:ALL ``` + ### Add it to the kvm access group (if available): + ```shell adduser runner kvm ``` + ### Switch to the new user and then create a workspace folder in its home directory: + ```shell mkdir actions-runner && cd actions-runner ``` + ### Download the latest version of actions-runner-linux-x64 from https://github.com/rust-lang/gha-runner/releases + ```shell curl -o actions-runner-linux-x64-X.X.X.tar.gz -L https://github.com/rust-lang/gha-runner/releases/download/vX.X.X-rust1/actions-runner-linux-x64-X.X.X-rust1.tar.gz ``` + ### Extract the tar archive + ```shell tar xzf ./actions-runner-linux-x64-X.X.X.tar.gz ``` + ### Link the runner to the repository + ```shell ./config.sh --url https://github.com/SerenityOS/serenity --token INSERT_SECRET_TOKEN_HERE ``` + ### Configure the runner to protect against malicious PRs by adding the following line to .env: + ```shell RUST_WHITELISTED_EVENT_NAME=push ``` + ### Configure the maximum runner threads by adding the following line to .env: + ```shell MAX_RUNNER_THREADS=XXX ``` + If you are setting up multiple runners on the same machine, this setting can be used to divvy up the cores, if you're only setting up one runner, this can just be set to the server's core count + ### Install the runner as a service + ```shell sudo ./svc.sh install ``` + ### Start the runner + ```shell sudo ./svc.sh start ``` diff --git a/Documentation/SmartPointers.md b/Documentation/SmartPointers.md index b9d617b6a02..b466e2d0120 100644 --- a/Documentation/SmartPointers.md +++ b/Documentation/SmartPointers.md @@ -1,14 +1,15 @@ # SerenityOS smart pointers ----- +--- + ## Introduction There are three main C++ smart pointer types used in SerenityOS. Each type describes the ownership (or lack thereof) of the pointee. The reason for using these pointers is to make it explicit through code who owns which resources, and how ownership is transferred. They also serve as a guard against memory leaks and use-after-free bugs. +--- ----- ## OwnPtr\<T\> and NonnullOwnPtr\<T\> `OwnPtr` is used for single-owner objects. An object held in an `OwnPtr` is owned by that `OwnPtr`, and not by anybody else. @@ -64,11 +65,12 @@ Any (possibly null) pointer to `T` can be turned into an `OwnPtr<T>` by the glob OwnPtr<Foo> my_object = adopt_own_if_nonnull(new (nothrow) Foo); ``` -In this case, the *non-throwing* `new` should be used to construct the raw pointer, which returns null if the allocation fails, instead of aborting the program. +In this case, the _non-throwing_ `new` should be used to construct the raw pointer, which returns null if the allocation fails, instead of aborting the program. **Note:** Always prefer the helper functions to manual construction. ----- +--- + ## RefPtr\<T\> and NonnullRefPtr\<T\> `RefPtr` is used for multiple-owner objects. An object held by a `RefPtr` is owned together by every pointer pointing to that object. @@ -98,7 +100,6 @@ NonnullRefPtr<Bar> our_object = make_ref_counted<Bar>(); NonnullRefPtr<Bar> another_owner = our_object; ``` - The `try_make_ref_counted<T>()` function constructs an object wrapped in `ErrorOr<NonnullRefPtr<T>>` which may be an error if the allocation does not succeed. This allows the calling code to handle allocation failure as it wishes. All arguments passed to it are forwarded to `T`'s constructor. ```cpp @@ -129,11 +130,13 @@ Any (possibly null) pointer to a reference-counted object can can be turned into ```cpp RefPtr<Bar> our_object = adopt_ref_if_nonnull(new (nothrow) Bar); ``` -In this case, the *non-throwing* `new` should be used to construct the raw pointer, which returns null if the allocation fails, instead of aborting the program. + +In this case, the _non-throwing_ `new` should be used to construct the raw pointer, which returns null if the allocation fails, instead of aborting the program. **Note:** Always prefer the helper functions to manual construction. ----- +--- + ## WeakPtr\<T\> `WeakPtr` is used for objects that somebody else owns. When the pointee of a `WeakPtr` is deleted, the `WeakPtr` will magically become null. diff --git a/Documentation/SpiceIntegration.md b/Documentation/SpiceIntegration.md index a5c6a4997d2..76db8d411cc 100644 --- a/Documentation/SpiceIntegration.md +++ b/Documentation/SpiceIntegration.md @@ -4,8 +4,8 @@ 1. Build QEMU via `Toolchain/BuildQemu.sh` 2. Install virt-viewer 8.0 - * On 23.04+ just do `sudo apt-get install virt-viewer` - * For earlier versions you need to build it from source (see below). + - On 23.04+ just do `sudo apt-get install virt-viewer` + - For earlier versions you need to build it from source (see below). 3. export SERENITY_SPICE=1 4. Meta/serenity.sh run @@ -13,19 +13,21 @@ **Note:** If you installed an old version from `apt` uninstall that first (`sudo apt-get purge virt-viewer`). - Install the build dependencies: + ``` sudo apt-get install libvirt-glib-1.0 libvirt-dev spice-client-gtk-3.0 spice-client-glib-2.0 intltool ``` Fetch and extract the sources: + ``` wget https://releases.pagure.org/virt-viewer/virt-viewer-8.0.tar.gz tar -xvf virt-viewer-8.0.tar.gz ``` Configure and build: + ``` cd ./virt-viewer-8.0 ./configure --with-spice-gtk @@ -33,6 +35,7 @@ make ``` Install: + ``` sudo make install ``` diff --git a/Documentation/StringFormatting.md b/Documentation/StringFormatting.md index ba494ce5660..8305987961b 100644 --- a/Documentation/StringFormatting.md +++ b/Documentation/StringFormatting.md @@ -37,13 +37,13 @@ ByteString::formatted("{0:.4}", "cool dude") == "cool"; In order, the format can contain: -- Fill character and alignment -- Sign -- `#` Hash -- `0` Zero -- Width -- Precision -- Type specifier +- Fill character and alignment +- Sign +- `#` Hash +- `0` Zero +- Width +- Precision +- Type specifier Each of these is optional. You can include any combination of them, but they must be in this order. @@ -55,15 +55,15 @@ space. (` `) The alignment characters are: -- `<`: Align left. -- `>`: Align right. -- `^`: Align centered. +- `<`: Align left. +- `>`: Align right. +- `^`: Align centered. ### Sign -- `+`: Always display a sign before the number. -- `-`: Display a sign for negative numbers only. -- (space): Display a sign for negative numbers, and a leading space for other numbers. +- `+`: Always display a sign before the number. +- `-`: Display a sign for negative numbers only. +- (space): Display a sign for negative numbers, and a leading space for other numbers. ### Hash @@ -71,9 +71,9 @@ The alignment characters are: For integer types, this adds the number-base prefix after the sign: -- `0b` for binary. -- `0` for octal. -- `0x` for hexadecimal. +- `0b` for binary. +- `0` for octal. +- `0x` for hexadecimal. ### Zero @@ -89,22 +89,22 @@ allows you to use an integer argument instead of a hard-coded number. ### Type specifiers -| Type | Effect | Example output | -|-----------|-----------------------|--------------------------| -| *nothing* | default format | Anything! :^) | -| b | binary | `110`, `0b000110` | -| B | binary uppercase | `110`, `0B000110` | -| d | decimal | `42`, `+0000042` | -| o | octal | `043` | -| x | hexadecimal | `ff0`, `0x00000ff0` | -| X | hexadecimal uppercase | `FF0`, `0X00000FF0` | -| c | character | `a` | -| s | string | `well, hello friends!` | -| p | pointer | `0xdeadc0de` | -| f | float | `1.234`, `-inf` | -| a | hex float | | -| A | hex float uppercase | | -| hex-dump | hexadecimal dump | `fdfdfdfd`, `3030 00` | +| Type | Effect | Example output | +| --------- | --------------------- | ---------------------- | +| _nothing_ | default format | Anything! :^) | +| b | binary | `110`, `0b000110` | +| B | binary uppercase | `110`, `0B000110` | +| d | decimal | `42`, `+0000042` | +| o | octal | `043` | +| x | hexadecimal | `ff0`, `0x00000ff0` | +| X | hexadecimal uppercase | `FF0`, `0X00000FF0` | +| c | character | `a` | +| s | string | `well, hello friends!` | +| p | pointer | `0xdeadc0de` | +| f | float | `1.234`, `-inf` | +| a | hex float | | +| A | hex float uppercase | | +| hex-dump | hexadecimal dump | `fdfdfdfd`, `3030 00` | Not all type specifiers are compatible with all input types, of course. diff --git a/Documentation/TransferringFiles.md b/Documentation/TransferringFiles.md index f3f1d6a750e..874530e3430 100644 --- a/Documentation/TransferringFiles.md +++ b/Documentation/TransferringFiles.md @@ -1,6 +1,7 @@ # Transferring files from QEMU to your host machine ## Method 1: WebServer + Serenity has a built-in web server which extends to your host machine. Open a new terminal and use the following command to start a WebServer instance for the current working directory: @@ -17,7 +18,7 @@ Then we just open `localhost:8000` on our host machine :^) ## Method 2: Mount the disk image -Another way is to mount Serenity's `_disk_image` to your host machine by using the following command on *nix systems (or inside WSL): +Another way is to mount Serenity's `_disk_image` to your host machine by using the following command on \*nix systems (or inside WSL): ```console cd "Build/${SERENITY_ARCH}" @@ -33,14 +34,16 @@ For WSL users: If you have the image on your native WSL drive (recommended), thi ## Method 4: Enable OpenSSH on host and use sftp client on SerenityOS -- Setup OpenSSH server on your host. -For windows: Google is your friend (https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse) -For linux: Google is your friend. -- Ensure that you already have a working SerenityOS working build. +- Setup OpenSSH server on your host. + For windows: Google is your friend (https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse) + For linux: Google is your friend. +- Ensure that you already have a working SerenityOS working build. + ```console $ Meta/serenity.sh rebuild-world ``` -- To enable OpenSSH package from SerenityOS: (initial directory is SerenityOS ROOT_DIR) + +- To enable OpenSSH package from SerenityOS: (initial directory is SerenityOS ROOT_DIR) ```console cd Ports @@ -49,11 +52,13 @@ cd openssh cd ../.. Meta/serenity.sh run ``` -- From within SerenityOS, check that you have a working sftp app: + +- From within SerenityOS, check that you have a working sftp app: ```console courage:~ $ sftp ``` + The expected response will be: ```console @@ -64,15 +69,16 @@ usage: sftp [-46aCfNpqrv] [-B buffer_size] [-b batchfile] [-c cipher] [-R num_requests] [-S program] [-s subsystem | sftp_server] destination ``` -- Assume that you have a working OpenSSH server as mentioned earlier, with an IP address of 192.168.0.11. -- Assume that you have a valid user on that host with account name user1. -- Assume that you are currently inside the folder from which you want to transfer the file(s) from. -- Local + +- Assume that you have a working OpenSSH server as mentioned earlier, with an IP address of 192.168.0.11. +- Assume that you have a valid user on that host with account name user1. +- Assume that you are currently inside the folder from which you want to transfer the file(s) from. +- Local User: anon -- Remote +- Remote User: user1 IP Address: 192.168.0.11 -- Connect to remote server via sftp +- Connect to remote server via sftp ```console courage:~ $ sftp user1@192.168.0.11 @@ -84,8 +90,9 @@ user1@'s password: Connected to 192.168.0.11 ``` -- By this time, you have successfully connected and logged on to the remote host. -- You can get more information by typing ` help `. -- The most often used (simplified) sftp commands are ` ls `, ` cd `, ` put [filename] `, ` get [filename] `, and ` quit `. I said simplified since the actual commands have many more options. -- Be aware that there will be a time you would think that nothing is happening since the cursor just stares back at you. It is always waiting for your next instruction. Typing ` quit ` or ` bye ` will close the program. -- Congratulations. Pat yourself at the back. + +- By this time, you have successfully connected and logged on to the remote host. +- You can get more information by typing `help`. +- The most often used (simplified) sftp commands are `ls`, `cd`, `put [filename]`, `get [filename]`, and `quit`. I said simplified since the actual commands have many more options. +- Be aware that there will be a time you would think that nothing is happening since the cursor just stares back at you. It is always waiting for your next instruction. Typing `quit` or `bye` will close the program. +- Congratulations. Pat yourself at the back. diff --git a/Documentation/Troubleshooting.md b/Documentation/Troubleshooting.md index d02d6bf6fd4..56e528c2fc0 100644 --- a/Documentation/Troubleshooting.md +++ b/Documentation/Troubleshooting.md @@ -99,11 +99,12 @@ extensions, or you try to use VirtualBox without using a x64 virtualization mode ### Boot fails with "Your computer does not support PAE. Halting!" -- If booting on bare metal, your CPU is too old to boot Serenity. -- If you're using VirtualBox, you need to enable PAE/NX. Check the instructions [here.](VirtualBox.md) -- If you're using QEMU, the [CPU model configuration](https://qemu-project.gitlab.io/qemu/system/qemu-cpu-models.html) is not exposing PAE. +- If booting on bare metal, your CPU is too old to boot Serenity. +- If you're using VirtualBox, you need to enable PAE/NX. Check the instructions [here.](VirtualBox.md) +- If you're using QEMU, the [CPU model configuration](https://qemu-project.gitlab.io/qemu/system/qemu-cpu-models.html) is not exposing PAE. ### Boot fails with "KVM doesn't support guest debugging" -- Update your host kernel to at least version `5.10`. This is the oldest kernel which properly supports the required KVM capability `KVM_CAP_SET_GUEST_DEBUG` (see corresponding [kernel commit](https://github.com/torvalds/linux/commit/b9b2782cd5)). -- Make sure that your distro has the qemu debug feature actually enabled (the corresponding check is [here](https://gitlab.com/qemu-project/qemu/-/blob/222059a0fccf4af3be776fe35a5ea2d6a68f9a0b/accel/kvm/kvm-all.c#L2540)). -- Or, disable KVM debugging by setting this env var when running serenity: `SERENITY_DISABLE_GDB_SOCKET=1` + +- Update your host kernel to at least version `5.10`. This is the oldest kernel which properly supports the required KVM capability `KVM_CAP_SET_GUEST_DEBUG` (see corresponding [kernel commit](https://github.com/torvalds/linux/commit/b9b2782cd5)). +- Make sure that your distro has the qemu debug feature actually enabled (the corresponding check is [here](https://gitlab.com/qemu-project/qemu/-/blob/222059a0fccf4af3be776fe35a5ea2d6a68f9a0b/accel/kvm/kvm-all.c#L2540)). +- Or, disable KVM debugging by setting this env var when running serenity: `SERENITY_DISABLE_GDB_SOCKET=1` diff --git a/Documentation/VMware.md b/Documentation/VMware.md index ad84fd7a080..7dd2d466820 100644 --- a/Documentation/VMware.md +++ b/Documentation/VMware.md @@ -1,18 +1,19 @@ # Serenity installation guide for VMware ## NOTICE + There are currently issues with running Serenity in VMware. Please refer to the [open issue](https://github.com/SerenityOS/serenity/issues/5716) for a list of currently known issues. Anything that doesn't currently work will be noted in this document. ## Creating the disk image -Before creating a disk image that will work in VMware, you will need to create a GRUB image as described in the [Serenity installation guide](BareMetalInstallation.md). Please skip the final step of that section, as that is only relevant for putting the image onto a real drive. You **cannot** use the same disk image created for QEMU. Using that image will halt immediately with the message ``FATAL: No bootable medium found! System halted.`` + +Before creating a disk image that will work in VMware, you will need to create a GRUB image as described in the [Serenity installation guide](BareMetalInstallation.md). Please skip the final step of that section, as that is only relevant for putting the image onto a real drive. You **cannot** use the same disk image created for QEMU. Using that image will halt immediately with the message `FATAL: No bootable medium found! System halted.` The easiest way to convert the disk image is with QEMU: -`` -qemu-img convert -O vmdk /path/to/grub_disk_image /path/to/output/serenityos.vmdk -`` +`qemu-img convert -O vmdk /path/to/grub_disk_image /path/to/output/serenityos.vmdk` ## Creating the virtual machine + Creating a SerenityOS virtual machine is similar to any other virtual machine. The main difference is using the already created VMDK disk image. **Please note that these instructions were written with VMware Player 15 in mind. Therefore, these instructions may not match exactly for past and future versions or VMware Workstation.** @@ -32,4 +33,3 @@ Creating a SerenityOS virtual machine is similar to any other virtual machine. T Please note that at the time of writing, audio and networking do not work in VMware. That is all you need to boot Serenity in VMware! - diff --git a/Documentation/VSCodeConfiguration.md b/Documentation/VSCodeConfiguration.md index 525f9248174..5e3c57caf30 100644 --- a/Documentation/VSCodeConfiguration.md +++ b/Documentation/VSCodeConfiguration.md @@ -1,14 +1,14 @@ # Visual Studio Code Project Configuration -Visual Studio Code requires some configuration files, and a tailored ``settings.json`` file to understand serenity. +Visual Studio Code requires some configuration files, and a tailored `settings.json` file to understand serenity. The WSL Remote extension allows you to use VS Code in Windows while using the normal WSL workflow. This works well, but for code comprehension speed you should put the Serenity directory on your WSL root partition. The recommended extensions for VS Code include: -- [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) -- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) -- [Jakt](https://github.com/SerenityOS/jakt/tree/main/editors/vscode) (See [Jakt](#jakt) for more information) +- [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) +- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) +- [Jakt](https://github.com/SerenityOS/jakt/tree/main/editors/vscode) (See [Jakt](#jakt) for more information) ## Code comprehension @@ -18,31 +18,31 @@ Clangd has the best support for cross-compiling workflows, especially if configu The official clangd extension can be used for C++ comprehension. It is recommended in general, as it is most likely to work on all platforms. -clangd uses ``compile_commands.json`` files to understand the project. CMake will generate these in either Build/x86_64, Build/x86_64clang, and Build/lagom. -Depending on which configuration you use most, set the CompilationDatabase configuration item in the below ``.clangd`` file accordingly. It goes at the root of your checkout (``serenity/.clangd``): +clangd uses `compile_commands.json` files to understand the project. CMake will generate these in either Build/x86_64, Build/x86_64clang, and Build/lagom. +Depending on which configuration you use most, set the CompilationDatabase configuration item in the below `.clangd` file accordingly. It goes at the root of your checkout (`serenity/.clangd`): ```yaml CompileFlags: - Add: [-D__serenity__] - CompilationDatabase: Build/x86_64 - + Add: [-D__serenity__] + CompilationDatabase: Build/x86_64 + Diagnostics: - UnusedIncludes: None - MissingIncludes: None + UnusedIncludes: None + MissingIncludes: None ``` The UnusedIncludes and MissingIncludes flags are used to disable the [Include Cleaner](https://clangd.llvm.org/design/include-cleaner) feature of newer clangd releases. It can be re-enabled if you don't mind the noisy inlay hints and problems in the problem view. -Run ``./Meta/serenity.sh run`` at least once to generate the ``compile_commands.json`` file. +Run `./Meta/serenity.sh run` at least once to generate the `compile_commands.json` file. -In addition to the ``.clangd`` file, the ``settings.json`` file below has a required ``clangd.arguments`` entry for ``--query-driver`` that allows clangd to find the cross-compiler's built-in include paths. +In addition to the `.clangd` file, the `settings.json` file below has a required `clangd.arguments` entry for `--query-driver` that allows clangd to find the cross-compiler's built-in include paths. #### Known issues -- Some distribution clangd packages still have issues identifying paths to the serenity cross-compilers' builtin include paths after supplying the ``--query-driver`` option from ``settings.json``. This has been seen on at least Debian. If the inlay hints suggest that ``<new>`` cannot be found, first triple check your configuration matches the ``.clangd`` file from this section, verify that you've run the OS via ``Meta/serenity.sh run``, and quadruple check your ``clangd.arguments`` section in the project-local ``settings.json`` file. If all of the above are correct, building ``clangd`` from the serenity clang toolchain is known to work. See [AdvancedBuildInstructions](AdvancedBuildInstructions.md#serenity-aware-clang-tools) for steps on how to build it from source. After building from source, be sure to set ``clangd.path`` in your ``settings.json`` to ``${workspaceFolder}/Toolchain/Local/clang/bin/clangd``. +- Some distribution clangd packages still have issues identifying paths to the serenity cross-compilers' builtin include paths after supplying the `--query-driver` option from `settings.json`. This has been seen on at least Debian. If the inlay hints suggest that `<new>` cannot be found, first triple check your configuration matches the `.clangd` file from this section, verify that you've run the OS via `Meta/serenity.sh run`, and quadruple check your `clangd.arguments` section in the project-local `settings.json` file. If all of the above are correct, building `clangd` from the serenity clang toolchain is known to work. See [AdvancedBuildInstructions](AdvancedBuildInstructions.md#serenity-aware-clang-tools) for steps on how to build it from source. After building from source, be sure to set `clangd.path` in your `settings.json` to `${workspaceFolder}/Toolchain/Local/clang/bin/clangd`. -- clangd has a tendency to crash when stressing bleeding edge compiler features. You can usually just restart it via the command palette. If that doesn't help, close currently open C++ files and/or switch branches before restarting, which helps sometimes. +- clangd has a tendency to crash when stressing bleeding edge compiler features. You can usually just restart it via the command palette. If that doesn't help, close currently open C++ files and/or switch branches before restarting, which helps sometimes. ### DSL syntax highlighting @@ -54,7 +54,7 @@ serialization format (no extension) as output by js with the -d option. This extension can be used as-is, but you need to point it to the custom Serenity compilers. Note that enabling the extension in the same workspace as the clangd and clang-format extensions will cause conflicts. If you choose to use Microsoft C/C++ Tools rather than clangd and clang-format, use the -following ``c_cpp_properties.json`` to circumvent some errors. Even with the configuration in place, the extension will likely still report errors related to types and methods not being found. +following `c_cpp_properties.json` to circumvent some errors. Even with the configuration in place, the extension will likely still report errors related to types and methods not being found. <details> <summary>.vscode/c_cpp_properties.json</summary> @@ -78,20 +78,13 @@ following ``c_cpp_properties.json`` to circumvent some errors. Even with the con "${workspaceFolder}/Userland/Services", "${workspaceFolder}/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/**" ], - "defines": [ - "DEBUG", - "__serenity__" - ], + "defines": ["DEBUG", "__serenity__"], "compilerPath": "${workspaceFolder}/Toolchain/Local/x86_64/bin/x86_64-pc-serenity-g++", "cStandard": "c17", "cppStandard": "c++23", "intelliSenseMode": "linux-gcc-x86", "compileCommands": "Build/x86_64/compile_commands.json", - "compilerArgs": [ - "-Wall", - "-Wextra", - "-Werror" - ], + "compilerArgs": ["-Wall", "-Wextra", "-Werror"], "browse": { "path": [ "${workspaceFolder}", @@ -115,11 +108,12 @@ following ``c_cpp_properties.json`` to circumvent some errors. Even with the con "version": 4 } ``` + </details> ## Formatting -clangd provides code formatting out of the box using the ``clang-format`` engine. ``clang-format`` support is also included with the Microsoft C/C++ tools (see above). The settings below include a key that makes the Microsoft extension use the proper style. +clangd provides code formatting out of the box using the `clang-format` engine. `clang-format` support is also included with the Microsoft C/C++ tools (see above). The settings below include a key that makes the Microsoft extension use the proper style. ## Settings @@ -134,7 +128,7 @@ These belong in the `.vscode/settings.json` of Serenity. "Toolchain/Tarballs/**": true, "Toolchain/Build/**": true, "Build/**": true, - "build/**": true, + "build/**": true }, "search.exclude": { "**/.git": true, @@ -142,7 +136,7 @@ These belong in the `.vscode/settings.json` of Serenity. "Toolchain/Tarballs/**": true, "Toolchain/Build/**": true, "Build/**": true, - "build/**": true, + "build/**": true }, // Force clang-format to respect Serenity's .clang-format style file. This is not necessary if you're not using the Microsoft C++ extension. "C_Cpp.clang_format_style": "file", @@ -185,19 +179,11 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo "problemMatcher": [ { "base": "$gcc", - "fileLocation": [ - "relative", - "${workspaceFolder}/Build/lagom" - ] + "fileLocation": ["relative", "${workspaceFolder}/Build/lagom"] } ], - "command": [ - "bash" - ], - "args": [ - "-c", - "\"Meta/serenity.sh build lagom\"" - ], + "command": ["bash"], + "args": ["-c", "\"Meta/serenity.sh build lagom\""], "presentation": { "echo": true, "reveal": "always", @@ -212,10 +198,7 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo "label": "build", "type": "shell", "command": "bash", - "args": [ - "-c", - "Meta/serenity.sh build ${input:arch} ${input:compiler}" - ], + "args": ["-c", "Meta/serenity.sh build ${input:arch} ${input:compiler}"], "problemMatcher": [ { "base": "$gcc", @@ -251,10 +234,7 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo "label": "launch", "type": "shell", "command": "bash", - "args": [ - "-c", - "Meta/serenity.sh run ${input:arch} ${input:compiler}" - ], + "args": ["-c", "Meta/serenity.sh run ${input:arch} ${input:compiler}"], "options": { "env": { // Put your custom run configuration here, e.g. SERENITY_RAM_SIZE @@ -288,10 +268,7 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo { "source": "KUBSan", "owner": "cpp", - "fileLocation": [ - "relative", - "${workspaceFolder}" - ], + "fileLocation": ["relative", "${workspaceFolder}"], "pattern": [ { "regexp": "KUBSAN: (.*)", @@ -334,20 +311,14 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo "description": "Compiler to use", "type": "pickString", "default": "GNU", - "options": [ - "GNU", - "Clang" - ] + "options": ["GNU", "Clang"] }, { "id": "arch", "description": "Architecture to compile for", "type": "pickString", "default": "x86_64", - "options": [ - "x86_64", - "aarch64" - ] + "options": ["x86_64", "aarch64"] } ] } @@ -358,6 +329,7 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo ### License snippet The following snippet may be useful if you want to quickly generate a license header, put it in `.vscode/serenity.code-snippets`: + ```json { "License": { diff --git a/Documentation/VirtualBox.md b/Documentation/VirtualBox.md index a31402805e8..4edcf8085d8 100644 --- a/Documentation/VirtualBox.md +++ b/Documentation/VirtualBox.md @@ -1,31 +1,28 @@ # Serenity installation guide for VirtualBox ## NOTICE + There are currently issues with running Serenity in VirtualBox. Please refer to the [open issue](https://github.com/SerenityOS/serenity/issues/2927) for a list of currently known issues. Anything that doesn't currently work will be noted in this document. ## Creating the disk image -Before creating a disk image that will work in VirtualBox, you will need to create a GRUB image as described in the [Serenity installation guide](BareMetalInstallation.md). Please skip the final step of that section, as that is only relevant for putting the image onto a real drive. You **cannot** use the same disk image created for QEMU. Using that image will halt immediately with the message ``FATAL: No bootable medium found! System halted.`` + +Before creating a disk image that will work in VirtualBox, you will need to create a GRUB image as described in the [Serenity installation guide](BareMetalInstallation.md). Please skip the final step of that section, as that is only relevant for putting the image onto a real drive. You **cannot** use the same disk image created for QEMU. Using that image will halt immediately with the message `FATAL: No bootable medium found! System halted.` There are a couple of ways to convert the disk image: If you have QEMU installed: -`` -qemu-img convert -O vdi /path/to/grub_disk_image /path/to/output/serenityos.vdi -`` +`qemu-img convert -O vdi /path/to/grub_disk_image /path/to/output/serenityos.vdi` If you only have VirtualBox installed: -`` -VBoxManage convertfromraw --format VDI /path/to/grub_disk_image /path/to/output/serenityos.vdi -`` +`VBoxManage convertfromraw --format VDI /path/to/grub_disk_image /path/to/output/serenityos.vdi` Set an identifier to the disk image, otherwise updating the disk image makes the identifiers no longer match up. -`` -VBoxManage internalcommands sethduuid serenityos.vdi 19850209-0000-0000-0000-000000000000 -`` +`VBoxManage internalcommands sethduuid serenityos.vdi 19850209-0000-0000-0000-000000000000` -Note that if you are on Windows and you do not have QEMU or VirtualBox in your PATH environment variable, you must be in the installation folder for the tool you're using. You will also need to put ``./`` in front of the command. +Note that if you are on Windows and you do not have QEMU or VirtualBox in your PATH environment variable, you must be in the installation folder for the tool you're using. You will also need to put `./` in front of the command. ## Creating the virtual machine + **Please note that these instructions were written with VirtualBox v6.1.12 in mind. Therefore, these instructions may not match exactly for past and future versions.** 1. Open the **Create Virtual Machine** dialog. Switch to **Expert Mode**. @@ -41,25 +38,30 @@ Reference image: ![](VirtualBox_Creation_Reference.png) ## Configuring the virtual machine to boot Serenity + Serenity will not be able to boot with the default configuration. There are a couple settings to adjust. Open **Settings** and: + 1. Go to **System**, open the **Processor** tab and tick **Enable PAE/NX**. 2. Go to **Audio** and set **Audio Controller** to **SoundBlaster 16**. There are a couple of settings to check: -- In **Storage**, click on the **Controller**. Make sure the controller type is PIIX4. PIIX3 and ICH6 are untested. Anything else is guaranteed not to work, as Serenity does not currently support them. -- In **Network** and in the **Advanced** drop down, make sure the **Adapter Type** is anything but **Intel PRO/1000 MT Desktop (82540EM)**. While it is the only adapter type Serenity currently supports, it does not currently work in VirtualBox. + +- In **Storage**, click on the **Controller**. Make sure the controller type is PIIX4. PIIX3 and ICH6 are untested. Anything else is guaranteed not to work, as Serenity does not currently support them. +- In **Network** and in the **Advanced** drop down, make sure the **Adapter Type** is anything but **Intel PRO/1000 MT Desktop (82540EM)**. While it is the only adapter type Serenity currently supports, it does not currently work in VirtualBox. Please note that at the time of writing, audio and networking do not work in VirtualBox. That is all you need to boot Serenity in VirtualBox! Read on for additional configuration you may want to use. ## Blinking cursor after GRUB menu + If you only see a blinking cursor after selecting an option in the GRUB menu, it is very likely you have encountered one of the errors listed in the [troubleshooting document.](Troubleshooting.md) -- Check that you have enabled PAE/NX in the **Settings** > **System** > **Processor** tab. -- If you are using a 64-bit disk image, check that **Version** is set to **Other/Unknown (64-bit)** instead of **Other/Unknown** in **Settings** > **General**. +- Check that you have enabled PAE/NX in the **Settings** > **System** > **Processor** tab. +- If you are using a 64-bit disk image, check that **Version** is set to **Other/Unknown (64-bit)** instead of **Other/Unknown** in **Settings** > **General**. ## Additional configuration (optional) + For serial debugging, go to **Serial Ports** and enable port 1. Feel free to set the **Port Mode** to anything if you know what you're doing. The recommended mode is **Raw File**. Set **Path/Address** to where you want to store the file. This must also include the file name. While the default 16 MB of video memory is more than enough to use the default resolution, it is not enough to use all the supported resolutions. If you want to use 2560x1080, you will need to supply at minimum 22 MB of video memory. diff --git a/Documentation/WritingManPages.md b/Documentation/WritingManPages.md index 6c169e2364d..a8103e2f483 100644 --- a/Documentation/WritingManPages.md +++ b/Documentation/WritingManPages.md @@ -58,10 +58,15 @@ All manpages should contain at least the following three sections: ```md ## Name + The manpage name, in the style described above. + ## Description + Main text of the manpage. + ## See also + List of related pages. ``` @@ -73,18 +78,31 @@ Applications in sections 1 and 8, especially command-line ones, must adhere to t ```md ## Name + program name - single-sentence descriptor of the program + ## Synopsis + Usage synopsis for invoking the program, within a `sh` code block. + ## Description + Prose description of the program. + ## Options + A list of optional arguments (flags) the program takes, with a brief description of each. More complex description, especially when options interact, should be part of the Description section. May be omitted if the program has no options. + ## Arguments + A list of (required) arguments the program takes, in the same format as the Options section. May be omitted if the program has no arguments. + ## Examples + Program invocation examples with resulting output. + ## See also + List of related pages. ``` diff --git a/Ladybird/README.md b/Ladybird/README.md index 2d9eb65c04d..1b1f1a05a01 100644 --- a/Ladybird/README.md +++ b/Ladybird/README.md @@ -20,18 +20,18 @@ Each tab has its own renderer process, which is sandboxed from the rest of the s All the core library support components are developed in the serenity monorepo: -- LibWeb: Web Rendering Engine -- LibJS: JavaScript Engine -- LibWasm: WebAssembly implementation -- LibCrypto/LibTLS: Cryptography primitives and Transport Layer Security (rather than OpenSSL) -- LibHTTP: HTTP/1.1 client -- LibGfx: 2D Graphics Library, Image Decoding and Rendering (rather than skia) -- LibArchive: Archive file format support (rather than libarchive, zlib) -- LibUnicode, LibLocale: Unicode and Locale support (rather than libicu) -- LibAudio, LibVideo: Audio and Video playback (rather than libav, ffmpeg) -- LibCore: Event Loop, OS Abstraction layer -- LibIPC: Inter-Process Communication -- ... and more! +- LibWeb: Web Rendering Engine +- LibJS: JavaScript Engine +- LibWasm: WebAssembly implementation +- LibCrypto/LibTLS: Cryptography primitives and Transport Layer Security (rather than OpenSSL) +- LibHTTP: HTTP/1.1 client +- LibGfx: 2D Graphics Library, Image Decoding and Rendering (rather than skia) +- LibArchive: Archive file format support (rather than libarchive, zlib) +- LibUnicode, LibLocale: Unicode and Locale support (rather than libicu) +- LibAudio, LibVideo: Audio and Video playback (rather than libav, ffmpeg) +- LibCore: Event Loop, OS Abstraction layer +- LibIPC: Inter-Process Communication +- ... and more! ## Building and Development diff --git a/Meta/Lagom/Fuzzers/FuzzilliJsInstructions.md b/Meta/Lagom/Fuzzers/FuzzilliJsInstructions.md index a8ebe8f54b8..7ab24a1f7f3 100644 --- a/Meta/Lagom/Fuzzers/FuzzilliJsInstructions.md +++ b/Meta/Lagom/Fuzzers/FuzzilliJsInstructions.md @@ -3,7 +3,7 @@ 1. Download a copy of the Fuzzilli repo from https://github.com/googleprojectzero/fuzzilli 2. Install Swift and make sure it's in your path environment variable. 3. Build FuzzilliJs as you would the other fuzzers. [See ReadMe.md in the parent folder.](https://github.com/SerenityOS/serenity/blob/master/Meta/Lagom/ReadMe.md) -5. Build Fuzzilli with ```swift build -c release``` -6. Run Fuzzilli with ```swift run -c release FuzzilliCli --profile=serenity /path/to/FuzzilliJs```. See ```swift run FuzzilliCli --help``` for options. +4. Build Fuzzilli with `swift build -c release` +5. Run Fuzzilli with `swift run -c release FuzzilliCli --profile=serenity /path/to/FuzzilliJs`. See `swift run FuzzilliCli --help` for options. Alternatively you can use `FuzzilliJs.dockerfile` to build & run Fuzzilli and FuzzilliJs with Docker or Podman. diff --git a/Meta/Lagom/ReadMe.md b/Meta/Lagom/ReadMe.md index c1bb17f31a3..76c201d497a 100644 --- a/Meta/Lagom/ReadMe.md +++ b/Meta/Lagom/ReadMe.md @@ -6,44 +6,47 @@ The Serenity C++ libraries, for other Operating Systems. If you want to bring the comfortable Serenity classes with you to another system, look no further. This is basically a "port" of the `AK` and `LibCore` libraries to generic \*nix systems. -*Lagom* is a Swedish word that means "just the right amount." ([Wikipedia](https://en.wikipedia.org/wiki/Lagom)) +_Lagom_ is a Swedish word that means "just the right amount." ([Wikipedia](https://en.wikipedia.org/wiki/Lagom)) Lagom is used by the Serenity project in the following ways: -- [Build tools](./Tools) required to build Serenity itself using Serenity's own C++ libraries are in Lagom. -- [Unit tests](../../Documentation/RunningTests.md) in CI are built using the Lagom build for host systems to ensure portability. -- [Continuous fuzzing](#fuzzing-on-oss-fuzz) is done with the help of OSS-fuzz using the Lagom build. -- [The Ladybird browser](../../Ladybird/README.md) uses Lagom to provide LibWeb and LibJS for non-Serenity systems. -- [ECMA 262 spec tests](https://serenityos.github.io/libjs-website/test262) for LibJS are run per-commit and tracked on [LibJS website](https://serenityos.github.io/libjs-website/). -- [Wasm spec tests](https://serenityos.github.io/libjs-website/wasm) for LibWasm are run per-commit and tracked on [LibJS website](https://serenityos.github.io/libjs-website/). -- [A Wasm LibJS Repl](https://serenityos.github.io/libjs-website/repl) using an Emscripten build of Lagom is hosted on [LibJS website](https://serenityos.github.io/libjs-website/). +- [Build tools](./Tools) required to build Serenity itself using Serenity's own C++ libraries are in Lagom. +- [Unit tests](../../Documentation/RunningTests.md) in CI are built using the Lagom build for host systems to ensure portability. +- [Continuous fuzzing](#fuzzing-on-oss-fuzz) is done with the help of OSS-fuzz using the Lagom build. +- [The Ladybird browser](../../Ladybird/README.md) uses Lagom to provide LibWeb and LibJS for non-Serenity systems. +- [ECMA 262 spec tests](https://serenityos.github.io/libjs-website/test262) for LibJS are run per-commit and tracked on [LibJS website](https://serenityos.github.io/libjs-website/). +- [Wasm spec tests](https://serenityos.github.io/libjs-website/wasm) for LibWasm are run per-commit and tracked on [LibJS website](https://serenityos.github.io/libjs-website/). +- [A Wasm LibJS Repl](https://serenityos.github.io/libjs-website/repl) using an Emscripten build of Lagom is hosted on [LibJS website](https://serenityos.github.io/libjs-website/). ## Using Lagom in an External Project + It is possible to use Lagom for your own projects outside of Serenity too! An example of this in use can be found in the [LibJS test262 runner](https://github.com/SerenityOS/libjs-test262). To implement this yourself: -- Download a copy of [SerenityOS/libjs-test262/cmake/FetchLagom.cmake](https://github.com/SerenityOS/libjs-test262/blob/7832c333c1504eecf1c5f9e4247aa6b34a52a3be/cmake/FetchLagom.cmake) and place it wherever you wish -- In your root `CMakeLists.txt`, add the following commands: - ```cmake - include(FetchContent) - include(cmake/FetchLagom.cmake) # If you've placed the file downloaded above differently, be sure to reflect that in this command :^) - ``` -- In addition, you will need to also add some compile options that Serenity uses to ensure no warnings or errors: - ```cmake - add_compile_options(-Wno-literal-suffix) # AK::StringView defines operator""sv, which GCC complains does not have an underscore. - add_compile_options(-fno-gnu-keywords) # JS::Value has a method named typeof, which also happens to be a GNU keyword. - ``` + +- Download a copy of [SerenityOS/libjs-test262/cmake/FetchLagom.cmake](https://github.com/SerenityOS/libjs-test262/blob/7832c333c1504eecf1c5f9e4247aa6b34a52a3be/cmake/FetchLagom.cmake) and place it wherever you wish +- In your root `CMakeLists.txt`, add the following commands: + ```cmake + include(FetchContent) + include(cmake/FetchLagom.cmake) # If you've placed the file downloaded above differently, be sure to reflect that in this command :^) + ``` +- In addition, you will need to also add some compile options that Serenity uses to ensure no warnings or errors: + ```cmake + add_compile_options(-Wno-literal-suffix) # AK::StringView defines operator""sv, which GCC complains does not have an underscore. + add_compile_options(-fno-gnu-keywords) # JS::Value has a method named typeof, which also happens to be a GNU keyword. + ``` Now, you can link against Lagom libraries. Things to keep in mind: -- You should prefer to use a library's `Lagom::` alias when linking - - Example: `Lagom::Core` vs `LibCore` -- If you still _need_ to use the C++ standard library, you may have to compile with the `AK_DONT_REPLACE_STD` macro. - - Serenity defines its own `move` and `forward` functions inside of `AK/StdLibExtras.h` that will clash with the standard library's definitions. This macro will make Serenity use the standard library's `move` and `forward` instead. -- If your application has name clashes with any names in AK, you may have to define `USING_AK_GLOBALLY=0` for the files that have visibility to both sets of headers. + +- You should prefer to use a library's `Lagom::` alias when linking + - Example: `Lagom::Core` vs `LibCore` +- If you still _need_ to use the C++ standard library, you may have to compile with the `AK_DONT_REPLACE_STD` macro. + - Serenity defines its own `move` and `forward` functions inside of `AK/StdLibExtras.h` that will clash with the standard library's definitions. This macro will make Serenity use the standard library's `move` and `forward` instead. +- If your application has name clashes with any names in AK, you may have to define `USING_AK_GLOBALLY=0` for the files that have visibility to both sets of headers. ## Fuzzing @@ -53,7 +56,7 @@ Lagom can be used to fuzz parts of SerenityOS's code base. Fuzzers can be run lo Lagom can be used to fuzz parts of SerenityOS's code base. This requires building with `clang`, so it's convenient to use a different build directory for that. Fuzzers work best with Address Sanitizer enabled. The fuzzer build requires code generators to be pre-built without fuzzing in a two stage build. -To build with LLVM's libFuzzer, invoke the ``BuildFuzzers.sh`` script with no arguments. +To build with LLVM's libFuzzer, invoke the `BuildFuzzers.sh` script with no arguments. ```sh ./BuildFuzzers.sh @@ -62,7 +65,7 @@ To build with LLVM's libFuzzer, invoke the ``BuildFuzzers.sh`` script with no ar (Note that we require clang >= 14, see the pick_clang() function in the script for the paths that are searched) -To build fuzzers without any kind of default instrumentation, pass the ``--standalone`` flag to ``BuildFuzzers.sh``: +To build fuzzers without any kind of default instrumentation, pass the `--standalone` flag to `BuildFuzzers.sh`: ```sh ./BuildFuzzers.sh --standalone @@ -107,10 +110,10 @@ Feel free to upload lots and lots files there, or use them for great good! https://oss-fuzz.com/ automatically runs all fuzzers in the Fuzzers/ subdirectory whose name starts with "Fuzz" and which are added to the build in `Fuzzers/CMakeLists.txt` if `ENABLE_FUZZERS_OSSFUZZ` is set. Looking for "serenity" on oss-fuzz.com finds interesting links, in particular: -* [known open bugs found by fuzzers](https://oss-fuzz.com/testcases?project=serenity&open=yes) - * [oss-fuzz bug tracker for these](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:serenity) -* [coverage report](https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_serenity/latest) -* [build logs](https://oss-fuzz-build-logs.storage.googleapis.com/index.html#serenity) +- [known open bugs found by fuzzers](https://oss-fuzz.com/testcases?project=serenity&open=yes) + - [oss-fuzz bug tracker for these](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:serenity) +- [coverage report](https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_serenity/latest) +- [build logs](https://oss-fuzz-build-logs.storage.googleapis.com/index.html#serenity) Here's [Serenity's OSS-Fuzz Config](https://github.com/google/oss-fuzz/tree/master/projects/serenity). The configuration runs the `BuildFuzzers.sh` script with the `--oss-fuzz` argument inside the OSS-Fuzz docker container. diff --git a/Meta/Websites/man.serenityos.org/index.md b/Meta/Websites/man.serenityos.org/index.md index d554b2576d6..e2e2cf8ace4 100644 --- a/Meta/Websites/man.serenityos.org/index.md +++ b/Meta/Websites/man.serenityos.org/index.md @@ -1,8 +1,8 @@ -- [Section 1: User Programs (applets, applications, utilities, etc.)](man1/index.html) -- [Section 2: System Calls (getuid, mount, pledge, sendfd, etc.)](man2/index.html) -- [Section 3: Library Functions (basename, isatty, POSIX functions, etc.)](man3/index.html) -- [Section 4: Special Files (audio, mem, etc.)](man4/index.html) -- [Section 5: File Formats (getopt convention, Shell, SystemServer)](man5/index.html) -- [Section 6: Games (2048, Chess, FlappyBug, etc.)](man6/index.html) -- [Section 7: Miscellanea (mitigations, sys filesystem, SystemServer, etc.)](man7/index.html) -- [Section 8: Sysadmin Tools (dmesg, pls, sysctl, useradd, etc.)](man8/index.html) +- [Section 1: User Programs (applets, applications, utilities, etc.)](man1/index.html) +- [Section 2: System Calls (getuid, mount, pledge, sendfd, etc.)](man2/index.html) +- [Section 3: Library Functions (basename, isatty, POSIX functions, etc.)](man3/index.html) +- [Section 4: Special Files (audio, mem, etc.)](man4/index.html) +- [Section 5: File Formats (getopt convention, Shell, SystemServer)](man5/index.html) +- [Section 6: Games (2048, Chess, FlappyBug, etc.)](man6/index.html) +- [Section 7: Miscellanea (mitigations, sys filesystem, SystemServer, etc.)](man7/index.html) +- [Section 8: Sysadmin Tools (dmesg, pls, sysctl, useradd, etc.)](man8/index.html) diff --git a/Meta/gn/README.md b/Meta/gn/README.md index aa480860a2a..824f9c4bb4c 100644 --- a/Meta/gn/README.md +++ b/Meta/gn/README.md @@ -35,14 +35,14 @@ If GN or ninja report a bunch of errors, it's likely that you need to create an If you modify `args.gn` outside of `gn args`, be sure to run `gn gen` again to regenerate the ninja files. - # Typical gn args On macOS, the default args should work out of the box. For compiling Ladybird there won't be any tailoring needed if you have Qt6 installed via homebrew and the Xcode tools installed. -On Ubuntu, it's likely that the default ``cc`` and ``c++`` will not be able to compile the project. For compiling Ladybird, a typical ``args.gn`` might look like the below: +On Ubuntu, it's likely that the default `cc` and `c++` will not be able to compile the project. For compiling Ladybird, a typical `args.gn` might look like the below: args.gn + ```gn # Set build arguments here. See `gn help buildargs`. # Chosen clang must be >= version 15.0.0 @@ -55,7 +55,7 @@ qt_install_lib="/usr/lib/x86_64-linux-gnu" qt_install_libexec="/usr/lib/qt6/libexec/" ``` -As with any gn project, ``gn args <build dir> --list`` is your best friend. +As with any gn project, `gn args <build dir> --list` is your best friend. # Running binaries from the GN build diff --git a/Ports/AvailablePorts.md b/Ports/AvailablePorts.md index 507d73f9eec..8c2bf1a498f 100644 --- a/Ports/AvailablePorts.md +++ b/Ports/AvailablePorts.md @@ -4,351 +4,351 @@ Please make sure to keep this list up to date when adding and updating ports. :^ This list is also available at [ports.serenityos.net](https://ports.serenityos.net) -| Port | Name | Version | Website | -|-----------------------------------------------------|-----------------------------------------------------------------|---------------------------|--------------------------------------------------------------------------------| -| [`abseil`](abseil/) | Abseil Common Libraries | 20230802.0 | https://abseil.io/ | -| [`aclock`](aclock/) | aclock | 2.3 | https://github.com/tenox7/aclock | -| [`acpica-tools`](acpica-tools/) | ACPI Component Architecture Project Userspace Utilities | R06_28_23 | https://github.com/acpica/acpica | -| [`alpine`](alpine/) | Alpine Email Client | 2.26 | https://alpineapp.email | -| [`angband`](angband/) | Angband | 4.2.5 | https://rephial.org | -| [`Another-World`](Another-World/) | Another World Bytecode Interpreter | | https://github.com/fabiensanglard/Another-World-Bytecode-Interpreter | -| [`aria2`](aria2/) | aria2 | 1.37.0 | https://aria2.github.io | -| [`awk`](awk/) | The One True Awk | 20220122 | https://github.com/onetrueawk/awk | -| [`backward-cpp`](backward-cpp/) | Backward-cpp | 65a769f | https://github.com/bombela/backward-cpp | -| [`bash`](bash/) | GNU Bash | 5.2.32 | https://www.gnu.org/software/bash/ | -| [`bass`](bass/) | Beneath a Steel Sky | cd-1.2 | https://www.scummvm.org/games | -| [`bc`](bc/) | bc | 6.5.0 | https://github.com/gavinhoward/bc | -| [`bdwgc`](bdwgc/) | Boehm-Demers-Weiser Garbage Collector (libgc) | 8.2.4 | https://github.com/ivmai/bdwgc | -| [`binutils`](binutils/) | GNU Binutils | 2.41 | https://www.gnu.org/software/binutils/ | -| [`bison`](bison/) | GNU Bison | 3.8.2 | https://www.gnu.org/software/bison/ | -| [`bochs`](bochs/) | Bochs x86 PC emulator | 2.7 | https://sourceforge.net/projects/bochs/ | -| [`boost`](boost/) | Boost C++ libraries | 1.83.0 | https://www.boost.org/ | -| [`brogue`](brogue/) | BrogueCE | 1.12 | https://github.com/tmewett/BrogueCE | -| [`brotli`](brotli/) | Brotli | 1.1.0 | https://github.com/google/brotli | -| [`byacc`](byacc/) | Berkeley Yacc | 20230521 | https://invisible-island.net/byacc/byacc.html | -| [`bzip2`](bzip2/) | bzip2 | 1.0.8 | https://sourceware.org/bzip2/ | -| [`bzip3`](bzip3/) | bzip3 | 1.3.2 | https://github.com/kspalaiologos/bzip3 | -| [`c-ares`](c-ares/) | c-ares | 1.19.0 | https://c-ares.org | -| [`c-ray`](c-ray/) | C-Ray | 8f30eb9 | https://github.com/vkoskiv/c-ray | -| [`ca-certificates`](ca-certificates/) | Mozilla CA certificate store | 2024-07-02 | https://curl.se/docs/caextract.html | -| [`carl`](carl/) | Crypto Ancienne Resource Loader | 1.5 | https://github.com/classilla/cryanc | -| [`cavestory`](cavestory/) | Cave Story | 2.6.5-1 | https://github.com/nxengine/nxengine-evo | -| [`cbonsai`](cbonsai/) | cbonsai | 1.3.1 | https://gitlab.com/jallbrit/cbonsai | -| [`ccache`](ccache/) | ccache | 4.8.3 | https://ccache.dev/ | -| [`cfunge`](cfunge/) | cfunge | 2bc4fb2 | https://github.com/VorpalBlade/cfunge/ | -| [`chester`](chester/) | Chester Gameboy Emulator | | https://github.com/veikkos/chester | -| [`chocolate-doom`](chocolate-doom/) | Chocolate Doom | 3.0.1 | https://www.chocolate-doom.org/ | -| [`chromaprint`](chromaprint/) | chromaprint | 1.5.1 | https://acoustid.org/ | -| [`citron`](citron/) | Citron Programming Language | 0.0.9.3 | https://github.com/alimpfard/citron | -| [`ClassiCube`](ClassiCube/) | ClassiCube | 1.3.6 | https://github.com/UnknownShadow200/ClassiCube | -| [`cmake`](cmake/) | CMake | 3.26.4 | https://cmake.org/ | -| [`cmatrix`](cmatrix/) | cmatrix | 3112b12 | https://github.com/abishekvashok/cmatrix | -| [`composer`](composer/) | Composer | 2.6.5 | https://getcomposer.org/ | -| [`coreutils`](coreutils/) | GNU core utilities | 9.4 | https://www.gnu.org/software/coreutils/ | -| [`cowsay`](cowsay/) | cowsay | 3.04 | https://github.com/tnalpgge/rank-amateur-cowsay | -| [`cpio`](cpio/) | GNU cpio archive utility | 2.14 | https://www.gnu.org/software/cpio/ | -| [`curl`](curl/) | curl | 8.9.1 | https://curl.se/ | -| [`dash`](dash/) | DASH | 0.5.10.2 | http://gondor.apana.org.au/~herbert/dash | -| [`deutex`](deutex/) | DeuTex | 5.2.2 | https://github.com/Doom-Utils/deutex | -| [`devilutionX`](devilutionX/) | DevilutionX | 1.5.3 | https://github.com/diasurgical/devilutionX | -| [`dialog`](dialog/) | Dialog | 1.3-20220526 | https://invisible-island.net/dialog/ | -| [`diffutils`](diffutils/) | GNU Diffutils | 3.10 | https://www.gnu.org/software/diffutils/ | -| [`dmidecode`](dmidecode/) | dmidecode | 3.6 | https://github.com/mirror/dmidecode | -| [`doom`](doom/) | DOOM | | https://github.com/ozkl/doomgeneric | -| [`dos2unix`](dos2unix/) | dos2unix | 7.5.1 | https://waterlan.home.xs4all.nl/dos2unix.html | -| [`dosbox-staging`](dosbox-staging/) | DOSBox Staging | 0.80.1 | https://dosbox-staging.github.io/ | -| [`dosfstools`](dosfstools/) | dosfstools utility suite | 4.2 | https://github.com/dosfstools/dosfstools/ | -| [`double-conversion`](double-conversion/) | double-conversion | 3.3.0 | https://github.com/google/double-conversion | -| [`doxygen`](doxygen/) | Doxygen | 1.9.7 | https://github.com/doxygen/doxygen | -| [`drascula`](drascula/) | Dráscula: The Vampire Strikes Back | 1.0 | https://www.scummvm.org/games/#games-drascula | -| [`dreamweb`](dreamweb/) | DreamWeb | 1.1 | https://www.scummvm.org/games/#games-dreamweb | -| [`dropbear`](dropbear/) | Dropbear SSH | 2022.82 | https://dropbear.nl/mirror/dropbear.html | -| [`dtc`](dtc/) | Device Tree Compiler | 1.7.0 | https://github.com/dgibson/dtc | -| [`dungeonrush`](dungeonrush/) | DungeonRush | 1.1-beta | https://github.com/Rapiz1/DungeonRush | -| [`e2fsprogs`](e2fsprogs/) | e2fsprogs | 1.47.0 | http://e2fsprogs.sourceforge.net/ | -| [`ed`](ed/) | GNU ed | 1.19 | https://www.gnu.org/software/ed/ | -| [`edid-decode`](edid-decode/) | edid-decode | 20220315.cb74358c2896 | https://git.linuxtv.org/edid-decode | -| [`editline`](editline/) | editline | 1.17.1 | https://github.com/troglobit/editline | -| [`emu2`](emu2/) | emu2 DOS emulator | 2021.01 | https://github.com/dmsc/emu2 | -| [`epsilon`](epsilon/) | graphical calculator simulator | 15.5.0 | https://github.com/numworks/epsilon | -| [`expat`](expat/) | Expat XML parser | 2.5.0 | https://libexpat.github.io/ | -| [`ffmpeg`](ffmpeg/) | ffmpeg | 7.0.2 | https://ffmpeg.org | -| [`figlet`](figlet/) | FIGlet | 2.2.5 | http://www.figlet.org/ | -| [`file`](file/) | file (determine file type) | 5.45 | https://www.darwinsys.com/file/ | -| [`findutils`](findutils/) | GNU findutils | 4.9.0 | https://www.gnu.org/software/findutils/ | -| [`fio`](fio/) | fio - Flexible I/O tester | 3.33 | https://fio.readthedocs.io/en/latest/ | -| [`flac`](flac/) | Free Lossless Audio Codec | 1.4.3 | https://xiph.org/flac/ | -| [`flare-engine`](flare-engine/) | Flare (engine) | 1.14 | https://flarerpg.org/ | -| [`flare-game`](flare-game/) | Flare (game) | 1.14 | https://flarerpg.org/ | -| [`flatbuffers`](flatbuffers/) | Flatbuffers | 2.0.0 | https://github.com/google/flatbuffers | -| [`flex`](flex/) | flex | 2.6.4 | https://github.com/westes/flex | -| [`fluidsynth`](fluidsynth/) | fluidsynth | 2.3.5 | https://www.fluidsynth.org/ | -| [`fontconfig`](fontconfig/) | Fontconfig | 2.14.2 | https://www.freedesktop.org/wiki/Software/fontconfig/ | -| [`fotaq`](fotaq/) | Flight of the Amazon Queen | 1.0 | https://www.scummvm.org/games/#games-queen | -| [`freeciv`](freeciv/) | Freeciv | 3.1.1 | http://freeciv.org/ | -| [`freedink`](freedink/) | FreeDink | 109.6 | https://www.gnu.org/software/freedink/ | -| [`freetype`](freetype/) | FreeType | 2.13.2 | https://www.freetype.org/ | -| [`frotz`](frotz/) | Frotz | 2.54 | https://gitlab.com/DavidGriffith/frotz | -| [`gawk`](gawk/) | GNU awk | 5.3.0 | https://www.gnu.org/software/gawk/ | -| [`gcc`](gcc/) | GNU Compiler Collection | 13.2.0 | https://gcc.gnu.org/ | -| [`gdb`](gdb/) | GNU Project Debugger | 11.2 | https://sourceware.org/gdb | -| [`gemrb`](gemrb/) | GemRB | 0.9.2 | https://gemrb.org/ | -| [`genemu`](genemu/) | Genesis / MegaDrive Emulator | e39f690 | https://github.com/rasky/genemu | -| [`genext2fs`](genext2fs/) | genext2fs | 1.5.0 | https://github.com/bestouff/genext2fs | -| [`gettext`](gettext/) | GNU gettext | 0.22.4 | https://www.gnu.org/software/gettext/ | -| [`giflib`](giflib/) | GIFLib | 5.2.1 | https://sourceforge.net/projects/giflib/ | -| [`git`](git/) | Git | 2.46.0 | https://git-scm.com/ | -| [`glib`](glib/) | GLib | 2.80.0 | https://wiki.gnome.org/Projects/GLib | -| [`glm`](glm/) | OpenGL Mathematics (GLM) | 0.9.9.8 | https://github.com/g-truc/glm | -| [`gltron`](gltron/) | GLTron | 0.70 | http://gltron.org | -| [`glu`](glu/) | Mesa GLU | 9.0.3 | https://gitlab.freedesktop.org/mesa/glu | -| [`gmp`](gmp/) | GNU Multiple Precision Arithmetic Library (GMP) | 6.3.0 | https://gmplib.org/ | -| [`gn`](gn/) | GN Meta Build System | 2023.07.12 | https://gn.googlesource.com/gn/ | -| [`gnuapl`](gnuapl/) | GNU APL | 1.8 | https://www.gnu.org/software/apl/ | -| [`gnucobol`](gnucobol/) | GnuCOBOL | 3.1.2 | https://gnucobol.sourceforge.io/ | -| [`gnupg`](gnupg/) | GnuPG | 2.4.5 | https://gnupg.org/software/index.html | -| [`gnuplot`](gnuplot/) | Gnuplot | 5.4.8 | http://www.gnuplot.info/ | -| [`gperf`](gperf/) | GNU gperf | 3.1 | https://www.gnu.org/software/gperf/ | -| [`gpgme`](gpgme/) | GnuPG Made Easy (GPGME) | 1.23.2 | https://gnupg.org/software/gpgme/index.html | -| [`grep`](grep/) | GNU Grep | 3.11 | https://www.gnu.org/software/grep/ | -| [`grepcidr`](grepcidr/) | grepcidr | 2.0 | http://www.pc-tools.net/unix/grepcidr/ | -| [`griffon`](griffon/) | The Griffon Legend | 1.0 | https://www.scummvm.org/games/#games-griffon | -| [`groff`](groff/) | GNU roff | 1.22.4 | https://www.gnu.org/software/groff/ | -| [`gsl`](gsl/) | GNU Scientific Library | 2.7.1 | https://www.gnu.org/software/gsl/ | -| [`guile`](guile/) | The GNU guile programming language | 3.0.8 | https://www.gnu.org/software/guile/ | -| [`gzip`](gzip/) | GNU gzip | 1.13 | https://www.gnu.org/software/gzip/ | -| [`halflife`](halflife/) | Half-Life | 2022.12.26 | https://github.com/FWGS/hlsdk-portable | -| [`harfbuzz`](harfbuzz/) | HarfBuzz | 9.0.0 | https://github.com/harfbuzz/harfbuzz | -| [`hatari`](hatari/) | Atari ST/STE/TT/Falcon emulator | 2.4.1 | https://hatari.tuxfamily.org/ | -| [`hexedit`](hexedit/) | A console-based hex editor | 1.6 | https://github.com/pixel/hexedit | -| [`highway`](highway/) | Highway | 1.0.7 | https://github.com/google/highway | -| [`imagemagick`](imagemagick/) | ImageMagick | 7.1.1-15 | https://imagemagick.org | -| [`imgcat`](imgcat/) | imgcat | 2.5.1 | https://github.com/eddieantonio/imgcat | -| [`indent`](indent/) | GNU indent | 2.2.11 | https://www.gnu.org/software/indent/ | -| [`isl`](isl/) | Integer Set Library | 0.26 | https://libisl.sourceforge.io/ | -| [`ja2`](ja2/) | Jagged Alliance 2 Stracciatella | 0.15.x | https://github.com/safarp/ja2-stracciatella/tree/0.15.x | -| [`jakt`](jakt/) | Jakt Programming Language | | https://github.com/SerenityOS/jakt | -| [`jdupes`](jdupes/) | jdupes, an enhanced fork of 'fdupes' | 1.27.3 | https://github.com/jbruchon/jdupes | -| [`jfduke3d`](jfduke3d/) | JonoF's Duke Nukem 3D Port | 41cd46b | https://github.com/jonof/jfduke3d | -| [`joe`](joe/) | joe's own editor | 4.6 | https://joe-editor.sourceforge.io/ | -| [`jot`](jot/) | jot (OpenBSD) | 6.6 | https://github.com/ibara/libpuffy | -| [`jq`](jq/) | jq | 1.7.1 | https://jqlang.github.io/jq/ | -| [`julius`](julius/) | julius | 1.7.0 | https://github.com/bvschaik/julius | -| [`kakoune`](kakoune/) | Modal text editor | e605ad8 | https://github.com/mawww/kakoune | -| [`klong`](klong/) | Klong | 20220315 | https://t3x.org/klong/ | -| [`lame`](lame/) | LAME Ain't an MP3 Encoder | 3.100 | https://lame.sourceforge.io/ | -| [`lcms2`](lcms2/) | Small-footprint color management engine | 2.15 | https://github.com/mm2/Little-CMS | -| [`less`](less/) | less | 643 | https://www.greenwoodsoftware.com/less/ | -| [`libarchive`](libarchive/) | libarchive | 3.7.1 | https://libarchive.org/ | -| [`libassuan`](libassuan/) | libassuan | 2.5.7 | https://gnupg.org/software/libassuan/index.html | -| [`libatomic_ops`](libatomic_ops/) | libatomic\_ops | 7.6.14 | https://www.hboehm.info/gc/ | -| [`libenet`](libenet/) | libenet | 1.3.17 | http://sauerbraten.org/enet/ | -| [`libexpat`](libexpat/) | Expat | 2.5.0 | https://libexpat.github.io/ | -| [`libffi`](libffi/) | libffi | 3.4.4 | https://www.sourceware.org/libffi/ | -| [`libfftw3`](libfftw3/) | Fastest Fourier Transform in the West (double precision) | 3.3.10 | https://www.fftw.org/ | -| [`libfftw3f`](libfftw3f/) | Fastest Fourier Transform in the West (single precision) | 3.3.10 | https://www.fftw.org/ | -| [`libfts`](libfts/) | libfts | 1.2.7 | https://github.com/void-linux/musl-fts | -| [`libfuse`](libfuse/) | libfuse | 3.16.2 | https://github.com/libfuse/libfuse | -| [`libgcrypt`](libgcrypt/) | libgcrypt | 1.10.3 | https://gnupg.org/software/libgcrypt/index.html | -| [`libgd`](libgd/) | libgd | 2.3.3 | https://libgd.github.io/ | -| [`libgpg-error`](libgpg-error/) | libgpg-error | 1.48 | https://gnupg.org/software/libgpg-error/index.html | -| [`libiconv`](libiconv/) | GNU libiconv | 1.17 | https://www.gnu.org/software/libiconv/ | -| [`libicu`](libicu/) | ICU | 73.2 | http://site.icu-project.org/ | -| [`libjodycode`](libjodycode/) | libjodycode | 3.1 | https://github.com/jbruchon/libjodycode | -| [`libjpeg`](libjpeg/) | libjpeg | 9e | https://ijg.org/ | -| [`libjxl`](libjxl/) | libjxl | 2023.09.11 | https://github.com/libjxl/libjxl | -| [`libksba`](libksba/) | libksba | 1.6.6 | https://gnupg.org/software/libksba/index.html | -| [`liblzf`](liblzf/) | LibLZF is a very small data compression library | 3.6 | http://software.schmorp.de/pkg/liblzf.html | -| [`libmad`](libmad/) | libmad | 0.15.1b | https://www.underbit.com/products/mad/ | -| [`libmikmod`](libmikmod/) | libmikmod | 3.3.11.1 | http://mikmod.sourceforge.net/ | -| [`libmodplug`](libmodplug/) | libmodplug | 0.8.9.0 | http://modplug-xmms.sourceforge.net/ | -| [`libmpeg2`](libmpeg2/) | libmpeg2 | 0.5.1 | https://libmpeg2.sourceforge.io/ | -| [`libmpg123`](libmpg123/) | libmpg123 | 1.31.3 | https://www.mpg123.de/ | -| [`libmt32emu`](libmt32emu/) | libmt32emu | 2.7.1 | https://github.com/munt/munt | -| [`libogg`](libogg/) | libogg | 1.3.5 | https://github.com/xiph/ogg | -| [`liboggz`](liboggz/) | liboggz | 1.1.1 | https://www.xiph.org/oggz/ | -| [`libopenal`](libopenal/) | OpenAL soft | 1.23.1 | https://openal-soft.org/ | -| [`libopus`](libopus/) | libopus | 1.3.1 | https://opus-codec.org/ | -| [`libphysfs`](libphysfs/) | PhysicsFS | 3.0.2 | https://icculus.org/physfs/ | -| [`libpng`](libpng/) | libpng | 1.6.43 | https://libpng.org/ | -| [`libpuffy`](libpuffy/) | libpuffy | 1.0 | https://github.com/ibara/libpuffy | -| [`libsamplerate`](libsamplerate/) | libsamplerate | 0.2.2 | https://libsndfile.github.io/libsamplerate/ | -| [`libsixel`](libsixel/) | libsixel | 1.8.6 | https://github.com/saitoha/libsixel | -| [`libslirp`](libslirp/) | libslirp | 4.7.0 | https://gitlab.freedesktop.org/slirp/libslirp | -| [`libsndfile`](libsndfile/) | libsndfile | 1.2.2 | https://libsndfile.github.io/libsndfile/ | -| [`libsodium`](libsodium/) | libsodium | 1.0.18 | https://doc.libsodium.org/ | -| [`libssh2`](libssh2/) | libssh2 | 1.11.0 | https://www.libssh2.org/ | -| [`libtheora`](libtheora/) | libtheora | 1.1.1 | https://www.theora.org/ | -| [`libtiff`](libtiff/) | libtiff | 4.5.1 | http://www.libtiff.org/ | -| [`libtool`](libtool/) | libtool | 2.4.7 | https://www.gnu.org/software/libtool/ | -| [`libunistring`](libunistring/) | libunistring | 1.1 | https://www.gnu.org/software/libunistring/ | -| [`libuuid`](libuuid/) | libuuid (from util-linux) | 2.39.2 | https://github.com/karelzak/util-linux/tree/master/libuuid | -| [`libuv`](libuv/) | libuv | 1.44.1 | https://github.com/libuv/libuv | -| [`libvorbis`](libvorbis/) | libvorbis | 1.3.7 | https://github.com/xiph/vorbis | -| [`libwebp`](libwebp/) | libwebp | 1.3.1 | https://github.com/webmproject/libwebp | -| [`libxml2`](libxml2/) | libxml2 | 2.11.5 | http://www.xmlsoft.org/ | -| [`libxmp`](libxmp/) | libxmp | 4.6.0 | https://github.com/libxmp/libxmp | -| [`libyaml`](libyaml/) | libyaml | 0.2.5 | https://pyyaml.org/wiki/LibYAML | -| [`libzip`](libzip/) | libzip | 1.10.1 | https://libzip.org/ | -| [`links`](links/) | Links web browser | 2.29 | http://links.twibright.com/ | -| [`lite-xl`](lite-xl/) | Lite-XL | 2.1.3 | https://lite-xl.com/ | -| [`llvm`](llvm/) | LLVM | 19.1.0 | https://llvm.org/ | -| [`lowdown`](lowdown/) | lowdown | 1.0.2 | https://kristaps.bsd.lv/lowdown/ | -| [`lrzip`](lrzip/) | lrzip | 0.651 | https://github.com/ckolivas/lrzip | -| [`lua`](lua/) | Lua | 5.4.6 | https://www.lua.org/ | -| [`luajit`](luajit/) | LuaJIT | 2.1.0-beta3 | https://luajit.org/luajit.html | -| [`luarocks`](luarocks/) | LuaRocks | 3.8.0 | https://luarocks.org/ | -| [`lure`](lure/) | Lure of the Temptress | 1.1 | https://www.scummvm.org/games/#games-lure | -| [`lxt`](lxt/) | linuXtree - an XTree Gold clone | 1.3b | http://stahlke.org/dan/lxt/ | -| [`lynx`](lynx/) | Lynx web browser | 2.8.9rel.1 | https://lynx.invisible-island.net/ | -| [`lz4`](lz4/) | lz4 - Extremely Fast Compression algorithm | 1.9.4 | https://github.com/lz4/lz4 | -| [`lzo`](lzo/) | LZO lossless data compression algorithm | 2.10 | https://www.oberhumer.com/opensource/lzo/ | -| [`lzop`](lzop/) | LZO lossless data compression utility | 1.04 | https://www.lzop.org/ | -| [`m4`](m4/) | GNU M4 | 1.4.19 | https://www.gnu.org/software/m4/ | -| [`make`](make/) | GNU make | 4.4.1 | https://www.gnu.org/software/make/ | -| [`mandoc`](mandoc/) | mandoc | 1.14.5 | https://mandoc.bsd.lv/ | -| [`mawk`](mawk/) | mawk | 1.3.4-20230808 | https://invisible-island.net/mawk/ | -| [`mbedtls`](mbedtls/) | Mbed TLS | 3.4.1 | https://tls.mbed.org/ | -| [`mc`](mc/) | Midnight Commander | 4.8.31 | https://midnight-commander.org/ | -| [`md4c`](md4c/) | Markdown for C | 0.4.8 | https://github.com/mity/md4c | -| [`mednafen`](mednafen/) | Mednafen (My Emulator Doesn't Need A Frickin' Excellent Name) | 1.31.0-UNSTABLE | https://mednafen.github.io/ | -| [`mgba`](mgba/) | Game Boy, Game Boy Color and Game Boy Advance emulator | 0.10.2 | https://mgba.io/ | -| [`milkytracker`](milkytracker/) | milkytracker | 1.03.00 | https://github.com/milkytracker/MilkyTracker | -| [`mold`](mold/) | A Modern Linker | 1.5.1 | https://github.com/rui314/mold | -| [`mpc`](mpc/) | GNU Multiple Precision Complex Library (MPC) | 1.3.1 | http://www.multiprecision.org/mpc/ | -| [`mpfr`](mpfr/) | GNU Multiple Precision Floating-Point Reliable Library (MPFR) | 4.2.1 | https://www.mpfr.org/ | -| [`mrsh`](mrsh/) | mrsh | cd3c3a4 | https://mrsh.sh/ | -| [`mruby`](mruby/) | mruby | 3.0.0 | https://mruby.org/ | -| [`mysthous`](mysthous/) | Hi-Res Adventure #1: Mystery House | 1.0 | https://www.scummvm.org/games/#games-hires1 | -| [`nano`](nano/) | GNU nano | 7.2 | https://www.nano-editor.org/ | -| [`nasm`](nasm/) | Netwide Assembler (NASM) | 2.16.01 | https://www.nasm.us/ | -| [`ncdu`](ncdu/) | Ncdu | 1.18.1 | https://dev.yorhel.nl/ncdu | -| [`ncurses`](ncurses/) | ncurses | 6.5 | https://invisible-island.net/ncurses/announce.html | -| [`neofetch`](neofetch/) | neofetch | 7.1.0 | https://github.com/dylanaraps/neofetch | -| [`nesalizer`](nesalizer/) | Nesalizer | 5bb0458 | https://github.com/ulfalizer/nesalizer | -| [`nethack`](nethack/) | nethack | 3.6.7 | https://www.nethack.org/ | -| [`ninja`](ninja/) | Ninja | 1.11.1 | https://ninja-build.org/ | -| [`nippon`](nippon/) | Nippon Safes Inc. | 1.0 | https://www.scummvm.org/games/#games-nippon | -| [`nlohmann-json`](nlohmann-json/) | JSON for Modern C++ | 3.11.2 | https://json.nlohmann.me/ | -| [`nnn`](nnn/) | nnn file manager | 4.8 | https://github.com/jarun/nnn | -| [`npiet`](npiet/) | Piet language interpreter | 1.3f | https://www.bertnase.de/npiet/ | -| [`npth`](npth/) | New GNU Portable Threads Library | 1.7 | https://gnupg.org/software/npth/index.html | -| [`ntbtls`](ntbtls/) | The Not Too Bad TLS Library | 0.3.2 | https://gnupg.org/software/ntbtls/index.html | -| [`nyancat`](nyancat/) | Nyancat | | https://github.com/klange/nyancat | -| [`ObjFW`](ObjFW/) | ObjFW | 1.1.2 | https://objfw.nil.im/ | -| [`oksh`](oksh/) | oksh | 7.1 | https://github.com/ibara/oksh | -| [`oniguruma`](oniguruma/) | oniguruma | 6.9.9 | https://github.com/kkos/oniguruma/ | -| [`OpenJDK`](OpenJDK/) | OpenJDK | 17.0.6 | https://openjdk.java.net/ | -| [`openjpeg`](openjpeg/) | OpenJPEG | 2.5.2 | https://www.openjpeg.org/ | -| [`openrct2`](openrct2/) | OpenRCT2 | 0.4.9 | https://openrct2.org/ | -| [`openssh`](openssh/) | OpenSSH | 9.0-94eb685 | https://github.com/openssh/openssh-portable | -| [`openssl`](openssl/) | OpenSSL | 3.3.1 | https://www.openssl.org/ | -| [`openttd`](openttd/) | OpenTTD | 13.4 | https://www.openttd.org/ | -| [`openttd-opengfx`](openttd-opengfx/) | OpenGFX graphics for OpenTTD | 7.1 | https://www.openttd.org/ | -| [`openttd-opensfx`](openttd-opensfx/) | OpenSFX audio files for OpenTTD | 1.0.3 | https://www.openttd.org/ | -| [`opentyrian`](opentyrian/) | OpenTyrian | 9750f8c | https://github.com/opentyrian/opentyrian | -| [`opfor`](opfor/) | Half-Life: Opposing Force | 2022.12.26 | https://github.com/FWGS/hlsdk-portable | -| [`optipng`](optipng/) | OptiPNG | 0.7.7 | http://optipng.sourceforge.net/ | -| [`opusfile`](opusfile/) | opusfile | 0.12 | https://opus-codec.org/ | -| [`p7zip`](p7zip/) | p7zip | 17.04 | https://github.com/jinfeihan57/p7zip | -| [`pacman`](pacman/) | Pacman | b6241a3 | https://github.com/ebuc99/pacman | -| [`patch`](patch/) | patch (GNU) | 2.7.6 | https://savannah.gnu.org/projects/patch/ | -| [`patchelf`](patchelf/) | Utility for modifying existing ELF executables and libraries | 0.18.0 | https://github.com/NixOS/patchelf/ | -| [`pcre`](pcre/) | Perl-compatible Regular Expressions (PCRE) | 8.45 | https://www.pcre.org/ | -| [`pcre2`](pcre2/) | Perl-compatible Regular Expressions (PCRE2) | 10.44 | https://www.pcre.org/ | -| [`perl5`](perl5/) | Perl | 5.40.0 | https://www.perl.org/ | -| [`pfetch`](pfetch/) | pfetch | a906ff8 | https://github.com/dylanaraps/pfetch/ | -| [`php`](php/) | PHP | 8.2.10 | https://www.php.net/ | -| [`pixman`](pixman/) | pixman | 0.42.2 | http://pixman.org | -| [`pkgconf`](pkgconf/) | pkgconf | 2.0.2 | https://github.com/pkgconf/pkgconf | -| [`poppler`](poppler/) | Poppler is a PDF rendering library | 24.02.0 | https://poppler.freedesktop.org/ | -| [`potrace`](potrace/) | Bitmap tracing utility | 1.16 | https://potrace.sourceforge.net/ | -| [`powdertoy`](powdertoy/) | The Powder Toy | 96.2.350 | https://powdertoy.co.uk/ | -| [`prboom-plus`](prboom-plus/) | PrBoom+ | 2.6.2 | https://prboom-plus.sourceforge.io/ | -| [`printf`](printf/) | printf (OpenBSD) | 6.6 | https://github.com/ibara/libpuffy | -| [`protobuf`](protobuf/) | Protocol Buffers | 24.3 | https://protobuf.dev/ | -| [`pt2-clone`](pt2-clone/) | ProTracker 2 clone | 1.63 | https://github.com/8bitbubsy/pt2-clone | -| [`pv`](pv/) | Pipe Viewer | 1.6.20 | http://www.ivarch.com/programs/pv.shtml | -| [`python3`](python3/) | Python | 3.12.4 | https://www.python.org/ | -| [`qemu`](qemu/) | QEMU | 8.1.3 | https://qemu.org | -| [`qoi`](qoi/) | Quite OK Image Format for fast, lossless image compression | 351450e | https://github.com/phoboslab/qoi | -| [`qt6-qt5compat`](qt6-qt5compat/) | Qt6 Qt5Compat | 6.4.0 | https://doc.qt.io/qt-6/qtcore5-index.html | -| [`qt6-qtbase`](qt6-qtbase/) | Qt6 QtBase | 6.4.0 | https://qt.io | -| [`qt6-qtsvg`](qt6-qtsvg/) | Qt6 QtSVG | 6.4.0 | https://qt.io | -| [`qt6-serenity`](qt6-serenity/) | QSerenityPlatform | | https://github.com/SerenityPorts/QSerenityPlatform | -| [`quake`](quake/) | Quake | 0.65 | https://github.com/SerenityOS/SerenityQuake | -| [`quake2`](quake2/) | QuakeII | 0.1 | https://github.com/shamazmazum/quake2sdl | -| [`quake3`](quake3/) | QuakeIII | 1.34 | https://github.com/ioquake/ioq3 | -| [`r0`](r0/) | r0 (minimalistic commandline hexadecimal editor) | 0.9 | https://github.com/radareorg/r0 | -| [`radare2`](radare2/) | radare2 reverse engineering framework | 5.7.6 | https://github.com/radareorg/radare2 | -| [`readline`](readline/) | GNU Readline Library | 8.2 | https://tiswww.case.edu/php/chet/readline/rltop.html | -| [`RetroArch`](RetroArch/) | RetroArch | 1.19.1 | https://www.retroarch.com | -| [`RISCVEmu`](RISCVEmu/) | A Basic C++ RISC-V Emulator | ad8ad6a | https://github.com/IdanHo/RISCVEmu | -| [`rsync`](rsync/) | rsync | 3.2.7 | https://rsync.samba.org/ | -| [`rubberband`](rubberband/) | Rubberband | 3.3.0 | https://breakfastquay.com/rubberband/ | -| [`ruby`](ruby/) | Ruby | 3.2.2 | https://www.ruby-lang.org/ | -| [`rvvm`](rvvm/) | RVVM - The RISC-V Virtual Machine | 0.6 | https://github.com/LekKit/RVVM | -| [`sam`](sam/) | Software Automatic Mouth (SAM) | c86ea39 | https://github.com/vidarh/SAM | -| [`schismtracker`](schismtracker/) | Schism Tracker | 20240523 | https://schismtracker.org/ | -| [`scummvm`](scummvm/) | ScummVM | 2.8.1 | https://www.scummvm.org/ | -| [`sdl12-compat`](sdl12-compat/) | SDL2 compatibility layer for SDL 1.2 games | 1.2.64 | https://github.com/libsdl-org/sdl12-compat/ | -| [`SDL2`](SDL2/) | Simple DirectMedia Layer (SDL2) | 2.30.5 | https://github.com/libsdl-org/SDL | -| [`SDL2-GNUBoy`](SDL2-GNUBoy/) | SDL2 GNUBoy | 1.2.1 | https://github.com/AlexOberhofer/SDL2-GNUBoy | -| [`SDL2_gfx`](SDL2_gfx/) | SDL2\_gfx (Graphics primitives add-on for SDL2) | 1.0.4 | https://sourceforge.net/projects/sdl2gfx/ | -| [`SDL2_image`](SDL2_image/) | SDL2\_image (Image loading add-on for SDL2) | 2.6.3 | https://github.com/libsdl-org/SDL_image | -| [`SDL2_mixer`](SDL2_mixer/) | SDL2\_mixer (Audio mixer add-on for SDL2) | 2.6.3 | https://github.com/libsdl-org/SDL_mixer | -| [`SDL2_net`](SDL2_net/) | SDL2\_net (Network add-on for SDL2) | 2.2.0 | https://github.com/libsdl-org/SDL_net | -| [`SDL2_sound`](SDL2_sound/) | SDL2\_sound (Abstract soundfile decoder add-on for SDL2) | | https://github.com/icculus/SDL_sound | -| [`SDL2_ttf`](SDL2_ttf/) | SDL2\_ttf (TrueType Font add-on for SDL2) | 2.20.2 | https://github.com/libsdl-org/SDL_ttf | -| [`SDL_mixer`](SDL_mixer/) | SDL\_mixer (Audio mixer add-on for SDL 1.2) | 1.2.12 | https://www.libsdl.org/projects/SDL_mixer/release-1.2.html | -| [`SDL_sound`](SDL_sound/) | SDL\_sound (Abstract soundfile decoder add-on for SDL 1.2) | 1.0.3 | https://www.icculus.org/SDL_sound/ | -| [`SDLPoP`](SDLPoP/) | Prince of Persia game | | https://github.com/NagyD/SDLPoP | -| [`sed`](sed/) | GNU sed | 4.9 | https://www.gnu.org/software/sed/ | -| [`serenity-theming`](serenity-theming/) | SerenityOS theming | 955c253 | https://github.com/SerenityOS/theming | -| [`serious-sam-classic`](serious-sam-classic/) | Serious Sam - The First Encounter | 1.10.4 | https://github.com/tx00100xt/SeriousSamClassic | -| [`sfinx`](sfinx/) | Sfinx | 1.1 | https://www.scummvm.org/games/#games-sfinx | -| [`sl`](sl/) | Steam Locomotive (SL) | | https://github.com/mtoyoda/sl | -| [`soltys`](soltys/) | Soltys | 1.0 | https://www.scummvm.org/games/#games-soltys | -| [`SpaceCadetPinball`](SpaceCadetPinball/) | 3D Pinball for Windows - Space Cadet | 2.1.0 | https://github.com/k4zmu2a/SpaceCadetPinball | -| [`sparsehash`](sparsehash/) | Google's C++ associative containers | 2.0.4 | https://github.com/sparsehash/sparsehash | -| [`speexdsp`](speexdsp/) | Speex audio processing library | 1.2.1 | https://www.speex.org/ | -| [`sqlite`](sqlite/) | SQLite | 3460000 | https://www.sqlite.org/ | -| [`SRB2`](SRB2/) | Sonic Robo Blast 2 | 2.2.13 | https://www.srb2.org/ | -| [`ssmtp`](ssmtp/) | sSMTP is a simple MTA | 2.64-11 | https://wiki.debian.org/sSMTP | -| [`stb`](stb/) | stb single-file public domain libraries for C/C++ | f7f20f3 | https://github.com/nothings/stb | -| [`stockfish`](stockfish/) | Stockfish: A free and strong UCI chess engine | 16.1 | https://github.com/official-stockfish/Stockfish | -| [`stpuzzles`](stpuzzles/) | Simon Tatham's Portable Puzzle Collection | | https://www.chiark.greenend.org.uk/~sgtatham/puzzles/ | -| [`stress-ng`](stress-ng/) | stress-ng | 0.16.04 | https://github.com/ColinIanKing/stress-ng | -| [`Super-Mario`](Super-Mario/) | Super-Mario Clone | | https://github.com/Bennyhwanggggg/Super-Mario-Clone-Cpp | -| [`SuperTuxKart`](SuperTuxKart/) | Super Tux Kart | 1.4 | https://supertuxkart.net/ | -| [`tar`](tar/) | GNU tar | 1.35 | https://www.gnu.org/software/tar/ | -| [`taskwarrior`](taskwarrior/) | TODO list manager | 2.6.2 | https://taskwarrior.org/ | -| [`tcl`](tcl/) | Tcl | 8.6.12 | https://www.tcl-lang.org/ | -| [`thesilversearcher`](thesilversearcher/) | The Silver Searcher: A fast code-searching tool | 2.2.0 | https://github.com/ggreer/the_silver_searcher | -| [`tig`](tig/) | Tig: text-mode interface for Git | 2.5.8 | https://jonas.github.io/tig/ | -| [`timidity`](timidity/) | TiMidity++ | 2.15.0 | http://timidity.sourceforge.net | -| [`tinycc`](tinycc/) | Tiny C Compiler (TinyCC) | dev | https://github.com/TinyCC/tinycc | -| [`tinyscheme`](tinyscheme/) | TinyScheme Interpreter | 1.42 | https://sourceforge.net/projects/tinyscheme/ | -| [`tr`](tr/) | tr (OpenBSD) | 6.7 | https://github.com/ibara/libpuffy | -| [`tree`](tree/) | tree | 2.1.3 | https://github.com/Old-Man-Programmer/tree | -| [`tuxracer`](tuxracer/) | Tux Racer | 0.61 | http://tuxracer.sourceforge.net/ | -| [`vim`](vim/) | Vim | 8.2.4554 | https://www.vim.org/ | -| [`vitetris`](vitetris/) | vitetris | 0.59.1 | https://github.com/vicgeralds/vitetris | -| [`vlang`](vlang/) | V programming language | weekly.2021.31 | https://github.com/vlang/v | -| [`vttest`](vttest/) | vttest | 20240708 | https://invisible-island.net/vttest/ | -| [`VVVVVV`](VVVVVV/) | Terry Cavanagh's VVVVVV | 2.3.6 | https://github.com/TerryCavanagh/VVVVVV/ | -| [`wayland`](wayland/) | Wayland client libraries | 1.21.0 | https://wayland.freedesktop.org/ | -| [`wget`](wget/) | GNU Wget | 1.24.5 | https://www.gnu.org/software/wget/ | -| [`which`](which/) | GNU which | 2.21 | https://www.gnu.org/software/which/ | -| [`wireguard-tools`](wireguard-tools/) | WireGuard Tools | 1.0.20210914 | https://www.wireguard.com/ | -| [`x264`](x264/) | x264 | 4613ac3 | https://www.videolan.org/developers/x264.html | -| [`x265`](x265/) | x265 | 3.6 | https://bitbucket.org/multicoreware/x265_git/wiki/Home | -| [`xash3d-fwgs`](xash3d-fwgs/) | Xash3D FWGS game engine | 2022.12.26 | https://github.com/FWGS/xash3d-fwgs | -| [`xmp-cli`](xmp-cli/) | Extended Module Player | 4.2.0 | https://github.com/libxmp/xmp-cli | -| [`xorriso`](xorriso/) | xorriso | 1.5.6 | https://www.gnu.org/software/xorriso | -| [`xz`](xz/) | xz | 5.6.2 | https://tukaani.org/xz/ | -| [`yasm`](yasm/) | Yasm Modular Assembler | 1.3.0 | https://yasm.tortall.net/ | -| [`zig`](zig/) | Zig programming language | 0.12.0-dev.141+ddf5859c2 | https://ziglang.org/ | -| [`zlib`](zlib/) | zlib | 1.3.1 | https://www.zlib.net/ | -| [`zsh`](zsh/) | Z Shell (Zsh) | 5.9 | https://www.zsh.org | -| [`zstd`](zstd/) | Zstandard | 1.5.6 | https://facebook.github.io/zstd/ | +| Port | Name | Version | Website | +| --------------------------------------------- | ------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------- | +| [`abseil`](abseil/) | Abseil Common Libraries | 20230802.0 | https://abseil.io/ | +| [`aclock`](aclock/) | aclock | 2.3 | https://github.com/tenox7/aclock | +| [`acpica-tools`](acpica-tools/) | ACPI Component Architecture Project Userspace Utilities | R06_28_23 | https://github.com/acpica/acpica | +| [`alpine`](alpine/) | Alpine Email Client | 2.26 | https://alpineapp.email | +| [`angband`](angband/) | Angband | 4.2.5 | https://rephial.org | +| [`Another-World`](Another-World/) | Another World Bytecode Interpreter | | https://github.com/fabiensanglard/Another-World-Bytecode-Interpreter | +| [`aria2`](aria2/) | aria2 | 1.37.0 | https://aria2.github.io | +| [`awk`](awk/) | The One True Awk | 20220122 | https://github.com/onetrueawk/awk | +| [`backward-cpp`](backward-cpp/) | Backward-cpp | 65a769f | https://github.com/bombela/backward-cpp | +| [`bash`](bash/) | GNU Bash | 5.2.32 | https://www.gnu.org/software/bash/ | +| [`bass`](bass/) | Beneath a Steel Sky | cd-1.2 | https://www.scummvm.org/games | +| [`bc`](bc/) | bc | 6.5.0 | https://github.com/gavinhoward/bc | +| [`bdwgc`](bdwgc/) | Boehm-Demers-Weiser Garbage Collector (libgc) | 8.2.4 | https://github.com/ivmai/bdwgc | +| [`binutils`](binutils/) | GNU Binutils | 2.41 | https://www.gnu.org/software/binutils/ | +| [`bison`](bison/) | GNU Bison | 3.8.2 | https://www.gnu.org/software/bison/ | +| [`bochs`](bochs/) | Bochs x86 PC emulator | 2.7 | https://sourceforge.net/projects/bochs/ | +| [`boost`](boost/) | Boost C++ libraries | 1.83.0 | https://www.boost.org/ | +| [`brogue`](brogue/) | BrogueCE | 1.12 | https://github.com/tmewett/BrogueCE | +| [`brotli`](brotli/) | Brotli | 1.1.0 | https://github.com/google/brotli | +| [`byacc`](byacc/) | Berkeley Yacc | 20230521 | https://invisible-island.net/byacc/byacc.html | +| [`bzip2`](bzip2/) | bzip2 | 1.0.8 | https://sourceware.org/bzip2/ | +| [`bzip3`](bzip3/) | bzip3 | 1.3.2 | https://github.com/kspalaiologos/bzip3 | +| [`c-ares`](c-ares/) | c-ares | 1.19.0 | https://c-ares.org | +| [`c-ray`](c-ray/) | C-Ray | 8f30eb9 | https://github.com/vkoskiv/c-ray | +| [`ca-certificates`](ca-certificates/) | Mozilla CA certificate store | 2024-07-02 | https://curl.se/docs/caextract.html | +| [`carl`](carl/) | Crypto Ancienne Resource Loader | 1.5 | https://github.com/classilla/cryanc | +| [`cavestory`](cavestory/) | Cave Story | 2.6.5-1 | https://github.com/nxengine/nxengine-evo | +| [`cbonsai`](cbonsai/) | cbonsai | 1.3.1 | https://gitlab.com/jallbrit/cbonsai | +| [`ccache`](ccache/) | ccache | 4.8.3 | https://ccache.dev/ | +| [`cfunge`](cfunge/) | cfunge | 2bc4fb2 | https://github.com/VorpalBlade/cfunge/ | +| [`chester`](chester/) | Chester Gameboy Emulator | | https://github.com/veikkos/chester | +| [`chocolate-doom`](chocolate-doom/) | Chocolate Doom | 3.0.1 | https://www.chocolate-doom.org/ | +| [`chromaprint`](chromaprint/) | chromaprint | 1.5.1 | https://acoustid.org/ | +| [`citron`](citron/) | Citron Programming Language | 0.0.9.3 | https://github.com/alimpfard/citron | +| [`ClassiCube`](ClassiCube/) | ClassiCube | 1.3.6 | https://github.com/UnknownShadow200/ClassiCube | +| [`cmake`](cmake/) | CMake | 3.26.4 | https://cmake.org/ | +| [`cmatrix`](cmatrix/) | cmatrix | 3112b12 | https://github.com/abishekvashok/cmatrix | +| [`composer`](composer/) | Composer | 2.6.5 | https://getcomposer.org/ | +| [`coreutils`](coreutils/) | GNU core utilities | 9.4 | https://www.gnu.org/software/coreutils/ | +| [`cowsay`](cowsay/) | cowsay | 3.04 | https://github.com/tnalpgge/rank-amateur-cowsay | +| [`cpio`](cpio/) | GNU cpio archive utility | 2.14 | https://www.gnu.org/software/cpio/ | +| [`curl`](curl/) | curl | 8.9.1 | https://curl.se/ | +| [`dash`](dash/) | DASH | 0.5.10.2 | http://gondor.apana.org.au/~herbert/dash | +| [`deutex`](deutex/) | DeuTex | 5.2.2 | https://github.com/Doom-Utils/deutex | +| [`devilutionX`](devilutionX/) | DevilutionX | 1.5.3 | https://github.com/diasurgical/devilutionX | +| [`dialog`](dialog/) | Dialog | 1.3-20220526 | https://invisible-island.net/dialog/ | +| [`diffutils`](diffutils/) | GNU Diffutils | 3.10 | https://www.gnu.org/software/diffutils/ | +| [`dmidecode`](dmidecode/) | dmidecode | 3.6 | https://github.com/mirror/dmidecode | +| [`doom`](doom/) | DOOM | | https://github.com/ozkl/doomgeneric | +| [`dos2unix`](dos2unix/) | dos2unix | 7.5.1 | https://waterlan.home.xs4all.nl/dos2unix.html | +| [`dosbox-staging`](dosbox-staging/) | DOSBox Staging | 0.80.1 | https://dosbox-staging.github.io/ | +| [`dosfstools`](dosfstools/) | dosfstools utility suite | 4.2 | https://github.com/dosfstools/dosfstools/ | +| [`double-conversion`](double-conversion/) | double-conversion | 3.3.0 | https://github.com/google/double-conversion | +| [`doxygen`](doxygen/) | Doxygen | 1.9.7 | https://github.com/doxygen/doxygen | +| [`drascula`](drascula/) | Dráscula: The Vampire Strikes Back | 1.0 | https://www.scummvm.org/games/#games-drascula | +| [`dreamweb`](dreamweb/) | DreamWeb | 1.1 | https://www.scummvm.org/games/#games-dreamweb | +| [`dropbear`](dropbear/) | Dropbear SSH | 2022.82 | https://dropbear.nl/mirror/dropbear.html | +| [`dtc`](dtc/) | Device Tree Compiler | 1.7.0 | https://github.com/dgibson/dtc | +| [`dungeonrush`](dungeonrush/) | DungeonRush | 1.1-beta | https://github.com/Rapiz1/DungeonRush | +| [`e2fsprogs`](e2fsprogs/) | e2fsprogs | 1.47.0 | http://e2fsprogs.sourceforge.net/ | +| [`ed`](ed/) | GNU ed | 1.19 | https://www.gnu.org/software/ed/ | +| [`edid-decode`](edid-decode/) | edid-decode | 20220315.cb74358c2896 | https://git.linuxtv.org/edid-decode | +| [`editline`](editline/) | editline | 1.17.1 | https://github.com/troglobit/editline | +| [`emu2`](emu2/) | emu2 DOS emulator | 2021.01 | https://github.com/dmsc/emu2 | +| [`epsilon`](epsilon/) | graphical calculator simulator | 15.5.0 | https://github.com/numworks/epsilon | +| [`expat`](expat/) | Expat XML parser | 2.5.0 | https://libexpat.github.io/ | +| [`ffmpeg`](ffmpeg/) | ffmpeg | 7.0.2 | https://ffmpeg.org | +| [`figlet`](figlet/) | FIGlet | 2.2.5 | http://www.figlet.org/ | +| [`file`](file/) | file (determine file type) | 5.45 | https://www.darwinsys.com/file/ | +| [`findutils`](findutils/) | GNU findutils | 4.9.0 | https://www.gnu.org/software/findutils/ | +| [`fio`](fio/) | fio - Flexible I/O tester | 3.33 | https://fio.readthedocs.io/en/latest/ | +| [`flac`](flac/) | Free Lossless Audio Codec | 1.4.3 | https://xiph.org/flac/ | +| [`flare-engine`](flare-engine/) | Flare (engine) | 1.14 | https://flarerpg.org/ | +| [`flare-game`](flare-game/) | Flare (game) | 1.14 | https://flarerpg.org/ | +| [`flatbuffers`](flatbuffers/) | Flatbuffers | 2.0.0 | https://github.com/google/flatbuffers | +| [`flex`](flex/) | flex | 2.6.4 | https://github.com/westes/flex | +| [`fluidsynth`](fluidsynth/) | fluidsynth | 2.3.5 | https://www.fluidsynth.org/ | +| [`fontconfig`](fontconfig/) | Fontconfig | 2.14.2 | https://www.freedesktop.org/wiki/Software/fontconfig/ | +| [`fotaq`](fotaq/) | Flight of the Amazon Queen | 1.0 | https://www.scummvm.org/games/#games-queen | +| [`freeciv`](freeciv/) | Freeciv | 3.1.1 | http://freeciv.org/ | +| [`freedink`](freedink/) | FreeDink | 109.6 | https://www.gnu.org/software/freedink/ | +| [`freetype`](freetype/) | FreeType | 2.13.2 | https://www.freetype.org/ | +| [`frotz`](frotz/) | Frotz | 2.54 | https://gitlab.com/DavidGriffith/frotz | +| [`gawk`](gawk/) | GNU awk | 5.3.0 | https://www.gnu.org/software/gawk/ | +| [`gcc`](gcc/) | GNU Compiler Collection | 13.2.0 | https://gcc.gnu.org/ | +| [`gdb`](gdb/) | GNU Project Debugger | 11.2 | https://sourceware.org/gdb | +| [`gemrb`](gemrb/) | GemRB | 0.9.2 | https://gemrb.org/ | +| [`genemu`](genemu/) | Genesis / MegaDrive Emulator | e39f690 | https://github.com/rasky/genemu | +| [`genext2fs`](genext2fs/) | genext2fs | 1.5.0 | https://github.com/bestouff/genext2fs | +| [`gettext`](gettext/) | GNU gettext | 0.22.4 | https://www.gnu.org/software/gettext/ | +| [`giflib`](giflib/) | GIFLib | 5.2.1 | https://sourceforge.net/projects/giflib/ | +| [`git`](git/) | Git | 2.46.0 | https://git-scm.com/ | +| [`glib`](glib/) | GLib | 2.80.0 | https://wiki.gnome.org/Projects/GLib | +| [`glm`](glm/) | OpenGL Mathematics (GLM) | 0.9.9.8 | https://github.com/g-truc/glm | +| [`gltron`](gltron/) | GLTron | 0.70 | http://gltron.org | +| [`glu`](glu/) | Mesa GLU | 9.0.3 | https://gitlab.freedesktop.org/mesa/glu | +| [`gmp`](gmp/) | GNU Multiple Precision Arithmetic Library (GMP) | 6.3.0 | https://gmplib.org/ | +| [`gn`](gn/) | GN Meta Build System | 2023.07.12 | https://gn.googlesource.com/gn/ | +| [`gnuapl`](gnuapl/) | GNU APL | 1.8 | https://www.gnu.org/software/apl/ | +| [`gnucobol`](gnucobol/) | GnuCOBOL | 3.1.2 | https://gnucobol.sourceforge.io/ | +| [`gnupg`](gnupg/) | GnuPG | 2.4.5 | https://gnupg.org/software/index.html | +| [`gnuplot`](gnuplot/) | Gnuplot | 5.4.8 | http://www.gnuplot.info/ | +| [`gperf`](gperf/) | GNU gperf | 3.1 | https://www.gnu.org/software/gperf/ | +| [`gpgme`](gpgme/) | GnuPG Made Easy (GPGME) | 1.23.2 | https://gnupg.org/software/gpgme/index.html | +| [`grep`](grep/) | GNU Grep | 3.11 | https://www.gnu.org/software/grep/ | +| [`grepcidr`](grepcidr/) | grepcidr | 2.0 | http://www.pc-tools.net/unix/grepcidr/ | +| [`griffon`](griffon/) | The Griffon Legend | 1.0 | https://www.scummvm.org/games/#games-griffon | +| [`groff`](groff/) | GNU roff | 1.22.4 | https://www.gnu.org/software/groff/ | +| [`gsl`](gsl/) | GNU Scientific Library | 2.7.1 | https://www.gnu.org/software/gsl/ | +| [`guile`](guile/) | The GNU guile programming language | 3.0.8 | https://www.gnu.org/software/guile/ | +| [`gzip`](gzip/) | GNU gzip | 1.13 | https://www.gnu.org/software/gzip/ | +| [`halflife`](halflife/) | Half-Life | 2022.12.26 | https://github.com/FWGS/hlsdk-portable | +| [`harfbuzz`](harfbuzz/) | HarfBuzz | 9.0.0 | https://github.com/harfbuzz/harfbuzz | +| [`hatari`](hatari/) | Atari ST/STE/TT/Falcon emulator | 2.4.1 | https://hatari.tuxfamily.org/ | +| [`hexedit`](hexedit/) | A console-based hex editor | 1.6 | https://github.com/pixel/hexedit | +| [`highway`](highway/) | Highway | 1.0.7 | https://github.com/google/highway | +| [`imagemagick`](imagemagick/) | ImageMagick | 7.1.1-15 | https://imagemagick.org | +| [`imgcat`](imgcat/) | imgcat | 2.5.1 | https://github.com/eddieantonio/imgcat | +| [`indent`](indent/) | GNU indent | 2.2.11 | https://www.gnu.org/software/indent/ | +| [`isl`](isl/) | Integer Set Library | 0.26 | https://libisl.sourceforge.io/ | +| [`ja2`](ja2/) | Jagged Alliance 2 Stracciatella | 0.15.x | https://github.com/safarp/ja2-stracciatella/tree/0.15.x | +| [`jakt`](jakt/) | Jakt Programming Language | | https://github.com/SerenityOS/jakt | +| [`jdupes`](jdupes/) | jdupes, an enhanced fork of 'fdupes' | 1.27.3 | https://github.com/jbruchon/jdupes | +| [`jfduke3d`](jfduke3d/) | JonoF's Duke Nukem 3D Port | 41cd46b | https://github.com/jonof/jfduke3d | +| [`joe`](joe/) | joe's own editor | 4.6 | https://joe-editor.sourceforge.io/ | +| [`jot`](jot/) | jot (OpenBSD) | 6.6 | https://github.com/ibara/libpuffy | +| [`jq`](jq/) | jq | 1.7.1 | https://jqlang.github.io/jq/ | +| [`julius`](julius/) | julius | 1.7.0 | https://github.com/bvschaik/julius | +| [`kakoune`](kakoune/) | Modal text editor | e605ad8 | https://github.com/mawww/kakoune | +| [`klong`](klong/) | Klong | 20220315 | https://t3x.org/klong/ | +| [`lame`](lame/) | LAME Ain't an MP3 Encoder | 3.100 | https://lame.sourceforge.io/ | +| [`lcms2`](lcms2/) | Small-footprint color management engine | 2.15 | https://github.com/mm2/Little-CMS | +| [`less`](less/) | less | 643 | https://www.greenwoodsoftware.com/less/ | +| [`libarchive`](libarchive/) | libarchive | 3.7.1 | https://libarchive.org/ | +| [`libassuan`](libassuan/) | libassuan | 2.5.7 | https://gnupg.org/software/libassuan/index.html | +| [`libatomic_ops`](libatomic_ops/) | libatomic_ops | 7.6.14 | https://www.hboehm.info/gc/ | +| [`libenet`](libenet/) | libenet | 1.3.17 | http://sauerbraten.org/enet/ | +| [`libexpat`](libexpat/) | Expat | 2.5.0 | https://libexpat.github.io/ | +| [`libffi`](libffi/) | libffi | 3.4.4 | https://www.sourceware.org/libffi/ | +| [`libfftw3`](libfftw3/) | Fastest Fourier Transform in the West (double precision) | 3.3.10 | https://www.fftw.org/ | +| [`libfftw3f`](libfftw3f/) | Fastest Fourier Transform in the West (single precision) | 3.3.10 | https://www.fftw.org/ | +| [`libfts`](libfts/) | libfts | 1.2.7 | https://github.com/void-linux/musl-fts | +| [`libfuse`](libfuse/) | libfuse | 3.16.2 | https://github.com/libfuse/libfuse | +| [`libgcrypt`](libgcrypt/) | libgcrypt | 1.10.3 | https://gnupg.org/software/libgcrypt/index.html | +| [`libgd`](libgd/) | libgd | 2.3.3 | https://libgd.github.io/ | +| [`libgpg-error`](libgpg-error/) | libgpg-error | 1.48 | https://gnupg.org/software/libgpg-error/index.html | +| [`libiconv`](libiconv/) | GNU libiconv | 1.17 | https://www.gnu.org/software/libiconv/ | +| [`libicu`](libicu/) | ICU | 73.2 | http://site.icu-project.org/ | +| [`libjodycode`](libjodycode/) | libjodycode | 3.1 | https://github.com/jbruchon/libjodycode | +| [`libjpeg`](libjpeg/) | libjpeg | 9e | https://ijg.org/ | +| [`libjxl`](libjxl/) | libjxl | 2023.09.11 | https://github.com/libjxl/libjxl | +| [`libksba`](libksba/) | libksba | 1.6.6 | https://gnupg.org/software/libksba/index.html | +| [`liblzf`](liblzf/) | LibLZF is a very small data compression library | 3.6 | http://software.schmorp.de/pkg/liblzf.html | +| [`libmad`](libmad/) | libmad | 0.15.1b | https://www.underbit.com/products/mad/ | +| [`libmikmod`](libmikmod/) | libmikmod | 3.3.11.1 | http://mikmod.sourceforge.net/ | +| [`libmodplug`](libmodplug/) | libmodplug | 0.8.9.0 | http://modplug-xmms.sourceforge.net/ | +| [`libmpeg2`](libmpeg2/) | libmpeg2 | 0.5.1 | https://libmpeg2.sourceforge.io/ | +| [`libmpg123`](libmpg123/) | libmpg123 | 1.31.3 | https://www.mpg123.de/ | +| [`libmt32emu`](libmt32emu/) | libmt32emu | 2.7.1 | https://github.com/munt/munt | +| [`libogg`](libogg/) | libogg | 1.3.5 | https://github.com/xiph/ogg | +| [`liboggz`](liboggz/) | liboggz | 1.1.1 | https://www.xiph.org/oggz/ | +| [`libopenal`](libopenal/) | OpenAL soft | 1.23.1 | https://openal-soft.org/ | +| [`libopus`](libopus/) | libopus | 1.3.1 | https://opus-codec.org/ | +| [`libphysfs`](libphysfs/) | PhysicsFS | 3.0.2 | https://icculus.org/physfs/ | +| [`libpng`](libpng/) | libpng | 1.6.43 | https://libpng.org/ | +| [`libpuffy`](libpuffy/) | libpuffy | 1.0 | https://github.com/ibara/libpuffy | +| [`libsamplerate`](libsamplerate/) | libsamplerate | 0.2.2 | https://libsndfile.github.io/libsamplerate/ | +| [`libsixel`](libsixel/) | libsixel | 1.8.6 | https://github.com/saitoha/libsixel | +| [`libslirp`](libslirp/) | libslirp | 4.7.0 | https://gitlab.freedesktop.org/slirp/libslirp | +| [`libsndfile`](libsndfile/) | libsndfile | 1.2.2 | https://libsndfile.github.io/libsndfile/ | +| [`libsodium`](libsodium/) | libsodium | 1.0.18 | https://doc.libsodium.org/ | +| [`libssh2`](libssh2/) | libssh2 | 1.11.0 | https://www.libssh2.org/ | +| [`libtheora`](libtheora/) | libtheora | 1.1.1 | https://www.theora.org/ | +| [`libtiff`](libtiff/) | libtiff | 4.5.1 | http://www.libtiff.org/ | +| [`libtool`](libtool/) | libtool | 2.4.7 | https://www.gnu.org/software/libtool/ | +| [`libunistring`](libunistring/) | libunistring | 1.1 | https://www.gnu.org/software/libunistring/ | +| [`libuuid`](libuuid/) | libuuid (from util-linux) | 2.39.2 | https://github.com/karelzak/util-linux/tree/master/libuuid | +| [`libuv`](libuv/) | libuv | 1.44.1 | https://github.com/libuv/libuv | +| [`libvorbis`](libvorbis/) | libvorbis | 1.3.7 | https://github.com/xiph/vorbis | +| [`libwebp`](libwebp/) | libwebp | 1.3.1 | https://github.com/webmproject/libwebp | +| [`libxml2`](libxml2/) | libxml2 | 2.11.5 | http://www.xmlsoft.org/ | +| [`libxmp`](libxmp/) | libxmp | 4.6.0 | https://github.com/libxmp/libxmp | +| [`libyaml`](libyaml/) | libyaml | 0.2.5 | https://pyyaml.org/wiki/LibYAML | +| [`libzip`](libzip/) | libzip | 1.10.1 | https://libzip.org/ | +| [`links`](links/) | Links web browser | 2.29 | http://links.twibright.com/ | +| [`lite-xl`](lite-xl/) | Lite-XL | 2.1.3 | https://lite-xl.com/ | +| [`llvm`](llvm/) | LLVM | 19.1.0 | https://llvm.org/ | +| [`lowdown`](lowdown/) | lowdown | 1.0.2 | https://kristaps.bsd.lv/lowdown/ | +| [`lrzip`](lrzip/) | lrzip | 0.651 | https://github.com/ckolivas/lrzip | +| [`lua`](lua/) | Lua | 5.4.6 | https://www.lua.org/ | +| [`luajit`](luajit/) | LuaJIT | 2.1.0-beta3 | https://luajit.org/luajit.html | +| [`luarocks`](luarocks/) | LuaRocks | 3.8.0 | https://luarocks.org/ | +| [`lure`](lure/) | Lure of the Temptress | 1.1 | https://www.scummvm.org/games/#games-lure | +| [`lxt`](lxt/) | linuXtree - an XTree Gold clone | 1.3b | http://stahlke.org/dan/lxt/ | +| [`lynx`](lynx/) | Lynx web browser | 2.8.9rel.1 | https://lynx.invisible-island.net/ | +| [`lz4`](lz4/) | lz4 - Extremely Fast Compression algorithm | 1.9.4 | https://github.com/lz4/lz4 | +| [`lzo`](lzo/) | LZO lossless data compression algorithm | 2.10 | https://www.oberhumer.com/opensource/lzo/ | +| [`lzop`](lzop/) | LZO lossless data compression utility | 1.04 | https://www.lzop.org/ | +| [`m4`](m4/) | GNU M4 | 1.4.19 | https://www.gnu.org/software/m4/ | +| [`make`](make/) | GNU make | 4.4.1 | https://www.gnu.org/software/make/ | +| [`mandoc`](mandoc/) | mandoc | 1.14.5 | https://mandoc.bsd.lv/ | +| [`mawk`](mawk/) | mawk | 1.3.4-20230808 | https://invisible-island.net/mawk/ | +| [`mbedtls`](mbedtls/) | Mbed TLS | 3.4.1 | https://tls.mbed.org/ | +| [`mc`](mc/) | Midnight Commander | 4.8.31 | https://midnight-commander.org/ | +| [`md4c`](md4c/) | Markdown for C | 0.4.8 | https://github.com/mity/md4c | +| [`mednafen`](mednafen/) | Mednafen (My Emulator Doesn't Need A Frickin' Excellent Name) | 1.31.0-UNSTABLE | https://mednafen.github.io/ | +| [`mgba`](mgba/) | Game Boy, Game Boy Color and Game Boy Advance emulator | 0.10.2 | https://mgba.io/ | +| [`milkytracker`](milkytracker/) | milkytracker | 1.03.00 | https://github.com/milkytracker/MilkyTracker | +| [`mold`](mold/) | A Modern Linker | 1.5.1 | https://github.com/rui314/mold | +| [`mpc`](mpc/) | GNU Multiple Precision Complex Library (MPC) | 1.3.1 | http://www.multiprecision.org/mpc/ | +| [`mpfr`](mpfr/) | GNU Multiple Precision Floating-Point Reliable Library (MPFR) | 4.2.1 | https://www.mpfr.org/ | +| [`mrsh`](mrsh/) | mrsh | cd3c3a4 | https://mrsh.sh/ | +| [`mruby`](mruby/) | mruby | 3.0.0 | https://mruby.org/ | +| [`mysthous`](mysthous/) | Hi-Res Adventure #1: Mystery House | 1.0 | https://www.scummvm.org/games/#games-hires1 | +| [`nano`](nano/) | GNU nano | 7.2 | https://www.nano-editor.org/ | +| [`nasm`](nasm/) | Netwide Assembler (NASM) | 2.16.01 | https://www.nasm.us/ | +| [`ncdu`](ncdu/) | Ncdu | 1.18.1 | https://dev.yorhel.nl/ncdu | +| [`ncurses`](ncurses/) | ncurses | 6.5 | https://invisible-island.net/ncurses/announce.html | +| [`neofetch`](neofetch/) | neofetch | 7.1.0 | https://github.com/dylanaraps/neofetch | +| [`nesalizer`](nesalizer/) | Nesalizer | 5bb0458 | https://github.com/ulfalizer/nesalizer | +| [`nethack`](nethack/) | nethack | 3.6.7 | https://www.nethack.org/ | +| [`ninja`](ninja/) | Ninja | 1.11.1 | https://ninja-build.org/ | +| [`nippon`](nippon/) | Nippon Safes Inc. | 1.0 | https://www.scummvm.org/games/#games-nippon | +| [`nlohmann-json`](nlohmann-json/) | JSON for Modern C++ | 3.11.2 | https://json.nlohmann.me/ | +| [`nnn`](nnn/) | nnn file manager | 4.8 | https://github.com/jarun/nnn | +| [`npiet`](npiet/) | Piet language interpreter | 1.3f | https://www.bertnase.de/npiet/ | +| [`npth`](npth/) | New GNU Portable Threads Library | 1.7 | https://gnupg.org/software/npth/index.html | +| [`ntbtls`](ntbtls/) | The Not Too Bad TLS Library | 0.3.2 | https://gnupg.org/software/ntbtls/index.html | +| [`nyancat`](nyancat/) | Nyancat | | https://github.com/klange/nyancat | +| [`ObjFW`](ObjFW/) | ObjFW | 1.1.2 | https://objfw.nil.im/ | +| [`oksh`](oksh/) | oksh | 7.1 | https://github.com/ibara/oksh | +| [`oniguruma`](oniguruma/) | oniguruma | 6.9.9 | https://github.com/kkos/oniguruma/ | +| [`OpenJDK`](OpenJDK/) | OpenJDK | 17.0.6 | https://openjdk.java.net/ | +| [`openjpeg`](openjpeg/) | OpenJPEG | 2.5.2 | https://www.openjpeg.org/ | +| [`openrct2`](openrct2/) | OpenRCT2 | 0.4.9 | https://openrct2.org/ | +| [`openssh`](openssh/) | OpenSSH | 9.0-94eb685 | https://github.com/openssh/openssh-portable | +| [`openssl`](openssl/) | OpenSSL | 3.3.1 | https://www.openssl.org/ | +| [`openttd`](openttd/) | OpenTTD | 13.4 | https://www.openttd.org/ | +| [`openttd-opengfx`](openttd-opengfx/) | OpenGFX graphics for OpenTTD | 7.1 | https://www.openttd.org/ | +| [`openttd-opensfx`](openttd-opensfx/) | OpenSFX audio files for OpenTTD | 1.0.3 | https://www.openttd.org/ | +| [`opentyrian`](opentyrian/) | OpenTyrian | 9750f8c | https://github.com/opentyrian/opentyrian | +| [`opfor`](opfor/) | Half-Life: Opposing Force | 2022.12.26 | https://github.com/FWGS/hlsdk-portable | +| [`optipng`](optipng/) | OptiPNG | 0.7.7 | http://optipng.sourceforge.net/ | +| [`opusfile`](opusfile/) | opusfile | 0.12 | https://opus-codec.org/ | +| [`p7zip`](p7zip/) | p7zip | 17.04 | https://github.com/jinfeihan57/p7zip | +| [`pacman`](pacman/) | Pacman | b6241a3 | https://github.com/ebuc99/pacman | +| [`patch`](patch/) | patch (GNU) | 2.7.6 | https://savannah.gnu.org/projects/patch/ | +| [`patchelf`](patchelf/) | Utility for modifying existing ELF executables and libraries | 0.18.0 | https://github.com/NixOS/patchelf/ | +| [`pcre`](pcre/) | Perl-compatible Regular Expressions (PCRE) | 8.45 | https://www.pcre.org/ | +| [`pcre2`](pcre2/) | Perl-compatible Regular Expressions (PCRE2) | 10.44 | https://www.pcre.org/ | +| [`perl5`](perl5/) | Perl | 5.40.0 | https://www.perl.org/ | +| [`pfetch`](pfetch/) | pfetch | a906ff8 | https://github.com/dylanaraps/pfetch/ | +| [`php`](php/) | PHP | 8.2.10 | https://www.php.net/ | +| [`pixman`](pixman/) | pixman | 0.42.2 | http://pixman.org | +| [`pkgconf`](pkgconf/) | pkgconf | 2.0.2 | https://github.com/pkgconf/pkgconf | +| [`poppler`](poppler/) | Poppler is a PDF rendering library | 24.02.0 | https://poppler.freedesktop.org/ | +| [`potrace`](potrace/) | Bitmap tracing utility | 1.16 | https://potrace.sourceforge.net/ | +| [`powdertoy`](powdertoy/) | The Powder Toy | 96.2.350 | https://powdertoy.co.uk/ | +| [`prboom-plus`](prboom-plus/) | PrBoom+ | 2.6.2 | https://prboom-plus.sourceforge.io/ | +| [`printf`](printf/) | printf (OpenBSD) | 6.6 | https://github.com/ibara/libpuffy | +| [`protobuf`](protobuf/) | Protocol Buffers | 24.3 | https://protobuf.dev/ | +| [`pt2-clone`](pt2-clone/) | ProTracker 2 clone | 1.63 | https://github.com/8bitbubsy/pt2-clone | +| [`pv`](pv/) | Pipe Viewer | 1.6.20 | http://www.ivarch.com/programs/pv.shtml | +| [`python3`](python3/) | Python | 3.12.4 | https://www.python.org/ | +| [`qemu`](qemu/) | QEMU | 8.1.3 | https://qemu.org | +| [`qoi`](qoi/) | Quite OK Image Format for fast, lossless image compression | 351450e | https://github.com/phoboslab/qoi | +| [`qt6-qt5compat`](qt6-qt5compat/) | Qt6 Qt5Compat | 6.4.0 | https://doc.qt.io/qt-6/qtcore5-index.html | +| [`qt6-qtbase`](qt6-qtbase/) | Qt6 QtBase | 6.4.0 | https://qt.io | +| [`qt6-qtsvg`](qt6-qtsvg/) | Qt6 QtSVG | 6.4.0 | https://qt.io | +| [`qt6-serenity`](qt6-serenity/) | QSerenityPlatform | | https://github.com/SerenityPorts/QSerenityPlatform | +| [`quake`](quake/) | Quake | 0.65 | https://github.com/SerenityOS/SerenityQuake | +| [`quake2`](quake2/) | QuakeII | 0.1 | https://github.com/shamazmazum/quake2sdl | +| [`quake3`](quake3/) | QuakeIII | 1.34 | https://github.com/ioquake/ioq3 | +| [`r0`](r0/) | r0 (minimalistic commandline hexadecimal editor) | 0.9 | https://github.com/radareorg/r0 | +| [`radare2`](radare2/) | radare2 reverse engineering framework | 5.7.6 | https://github.com/radareorg/radare2 | +| [`readline`](readline/) | GNU Readline Library | 8.2 | https://tiswww.case.edu/php/chet/readline/rltop.html | +| [`RetroArch`](RetroArch/) | RetroArch | 1.19.1 | https://www.retroarch.com | +| [`RISCVEmu`](RISCVEmu/) | A Basic C++ RISC-V Emulator | ad8ad6a | https://github.com/IdanHo/RISCVEmu | +| [`rsync`](rsync/) | rsync | 3.2.7 | https://rsync.samba.org/ | +| [`rubberband`](rubberband/) | Rubberband | 3.3.0 | https://breakfastquay.com/rubberband/ | +| [`ruby`](ruby/) | Ruby | 3.2.2 | https://www.ruby-lang.org/ | +| [`rvvm`](rvvm/) | RVVM - The RISC-V Virtual Machine | 0.6 | https://github.com/LekKit/RVVM | +| [`sam`](sam/) | Software Automatic Mouth (SAM) | c86ea39 | https://github.com/vidarh/SAM | +| [`schismtracker`](schismtracker/) | Schism Tracker | 20240523 | https://schismtracker.org/ | +| [`scummvm`](scummvm/) | ScummVM | 2.8.1 | https://www.scummvm.org/ | +| [`sdl12-compat`](sdl12-compat/) | SDL2 compatibility layer for SDL 1.2 games | 1.2.64 | https://github.com/libsdl-org/sdl12-compat/ | +| [`SDL2`](SDL2/) | Simple DirectMedia Layer (SDL2) | 2.30.5 | https://github.com/libsdl-org/SDL | +| [`SDL2-GNUBoy`](SDL2-GNUBoy/) | SDL2 GNUBoy | 1.2.1 | https://github.com/AlexOberhofer/SDL2-GNUBoy | +| [`SDL2_gfx`](SDL2_gfx/) | SDL2_gfx (Graphics primitives add-on for SDL2) | 1.0.4 | https://sourceforge.net/projects/sdl2gfx/ | +| [`SDL2_image`](SDL2_image/) | SDL2_image (Image loading add-on for SDL2) | 2.6.3 | https://github.com/libsdl-org/SDL_image | +| [`SDL2_mixer`](SDL2_mixer/) | SDL2_mixer (Audio mixer add-on for SDL2) | 2.6.3 | https://github.com/libsdl-org/SDL_mixer | +| [`SDL2_net`](SDL2_net/) | SDL2_net (Network add-on for SDL2) | 2.2.0 | https://github.com/libsdl-org/SDL_net | +| [`SDL2_sound`](SDL2_sound/) | SDL2_sound (Abstract soundfile decoder add-on for SDL2) | | https://github.com/icculus/SDL_sound | +| [`SDL2_ttf`](SDL2_ttf/) | SDL2_ttf (TrueType Font add-on for SDL2) | 2.20.2 | https://github.com/libsdl-org/SDL_ttf | +| [`SDL_mixer`](SDL_mixer/) | SDL_mixer (Audio mixer add-on for SDL 1.2) | 1.2.12 | https://www.libsdl.org/projects/SDL_mixer/release-1.2.html | +| [`SDL_sound`](SDL_sound/) | SDL_sound (Abstract soundfile decoder add-on for SDL 1.2) | 1.0.3 | https://www.icculus.org/SDL_sound/ | +| [`SDLPoP`](SDLPoP/) | Prince of Persia game | | https://github.com/NagyD/SDLPoP | +| [`sed`](sed/) | GNU sed | 4.9 | https://www.gnu.org/software/sed/ | +| [`serenity-theming`](serenity-theming/) | SerenityOS theming | 955c253 | https://github.com/SerenityOS/theming | +| [`serious-sam-classic`](serious-sam-classic/) | Serious Sam - The First Encounter | 1.10.4 | https://github.com/tx00100xt/SeriousSamClassic | +| [`sfinx`](sfinx/) | Sfinx | 1.1 | https://www.scummvm.org/games/#games-sfinx | +| [`sl`](sl/) | Steam Locomotive (SL) | | https://github.com/mtoyoda/sl | +| [`soltys`](soltys/) | Soltys | 1.0 | https://www.scummvm.org/games/#games-soltys | +| [`SpaceCadetPinball`](SpaceCadetPinball/) | 3D Pinball for Windows - Space Cadet | 2.1.0 | https://github.com/k4zmu2a/SpaceCadetPinball | +| [`sparsehash`](sparsehash/) | Google's C++ associative containers | 2.0.4 | https://github.com/sparsehash/sparsehash | +| [`speexdsp`](speexdsp/) | Speex audio processing library | 1.2.1 | https://www.speex.org/ | +| [`sqlite`](sqlite/) | SQLite | 3460000 | https://www.sqlite.org/ | +| [`SRB2`](SRB2/) | Sonic Robo Blast 2 | 2.2.13 | https://www.srb2.org/ | +| [`ssmtp`](ssmtp/) | sSMTP is a simple MTA | 2.64-11 | https://wiki.debian.org/sSMTP | +| [`stb`](stb/) | stb single-file public domain libraries for C/C++ | f7f20f3 | https://github.com/nothings/stb | +| [`stockfish`](stockfish/) | Stockfish: A free and strong UCI chess engine | 16.1 | https://github.com/official-stockfish/Stockfish | +| [`stpuzzles`](stpuzzles/) | Simon Tatham's Portable Puzzle Collection | | https://www.chiark.greenend.org.uk/~sgtatham/puzzles/ | +| [`stress-ng`](stress-ng/) | stress-ng | 0.16.04 | https://github.com/ColinIanKing/stress-ng | +| [`Super-Mario`](Super-Mario/) | Super-Mario Clone | | https://github.com/Bennyhwanggggg/Super-Mario-Clone-Cpp | +| [`SuperTuxKart`](SuperTuxKart/) | Super Tux Kart | 1.4 | https://supertuxkart.net/ | +| [`tar`](tar/) | GNU tar | 1.35 | https://www.gnu.org/software/tar/ | +| [`taskwarrior`](taskwarrior/) | TODO list manager | 2.6.2 | https://taskwarrior.org/ | +| [`tcl`](tcl/) | Tcl | 8.6.12 | https://www.tcl-lang.org/ | +| [`thesilversearcher`](thesilversearcher/) | The Silver Searcher: A fast code-searching tool | 2.2.0 | https://github.com/ggreer/the_silver_searcher | +| [`tig`](tig/) | Tig: text-mode interface for Git | 2.5.8 | https://jonas.github.io/tig/ | +| [`timidity`](timidity/) | TiMidity++ | 2.15.0 | http://timidity.sourceforge.net | +| [`tinycc`](tinycc/) | Tiny C Compiler (TinyCC) | dev | https://github.com/TinyCC/tinycc | +| [`tinyscheme`](tinyscheme/) | TinyScheme Interpreter | 1.42 | https://sourceforge.net/projects/tinyscheme/ | +| [`tr`](tr/) | tr (OpenBSD) | 6.7 | https://github.com/ibara/libpuffy | +| [`tree`](tree/) | tree | 2.1.3 | https://github.com/Old-Man-Programmer/tree | +| [`tuxracer`](tuxracer/) | Tux Racer | 0.61 | http://tuxracer.sourceforge.net/ | +| [`vim`](vim/) | Vim | 8.2.4554 | https://www.vim.org/ | +| [`vitetris`](vitetris/) | vitetris | 0.59.1 | https://github.com/vicgeralds/vitetris | +| [`vlang`](vlang/) | V programming language | weekly.2021.31 | https://github.com/vlang/v | +| [`vttest`](vttest/) | vttest | 20240708 | https://invisible-island.net/vttest/ | +| [`VVVVVV`](VVVVVV/) | Terry Cavanagh's VVVVVV | 2.3.6 | https://github.com/TerryCavanagh/VVVVVV/ | +| [`wayland`](wayland/) | Wayland client libraries | 1.21.0 | https://wayland.freedesktop.org/ | +| [`wget`](wget/) | GNU Wget | 1.24.5 | https://www.gnu.org/software/wget/ | +| [`which`](which/) | GNU which | 2.21 | https://www.gnu.org/software/which/ | +| [`wireguard-tools`](wireguard-tools/) | WireGuard Tools | 1.0.20210914 | https://www.wireguard.com/ | +| [`x264`](x264/) | x264 | 4613ac3 | https://www.videolan.org/developers/x264.html | +| [`x265`](x265/) | x265 | 3.6 | https://bitbucket.org/multicoreware/x265_git/wiki/Home | +| [`xash3d-fwgs`](xash3d-fwgs/) | Xash3D FWGS game engine | 2022.12.26 | https://github.com/FWGS/xash3d-fwgs | +| [`xmp-cli`](xmp-cli/) | Extended Module Player | 4.2.0 | https://github.com/libxmp/xmp-cli | +| [`xorriso`](xorriso/) | xorriso | 1.5.6 | https://www.gnu.org/software/xorriso | +| [`xz`](xz/) | xz | 5.6.2 | https://tukaani.org/xz/ | +| [`yasm`](yasm/) | Yasm Modular Assembler | 1.3.0 | https://yasm.tortall.net/ | +| [`zig`](zig/) | Zig programming language | 0.12.0-dev.141+ddf5859c2 | https://ziglang.org/ | +| [`zlib`](zlib/) | zlib | 1.3.1 | https://www.zlib.net/ | +| [`zsh`](zsh/) | Z Shell (Zsh) | 5.9 | https://www.zsh.org | +| [`zstd`](zstd/) | Zstandard | 1.5.6 | https://facebook.github.io/zstd/ | diff --git a/Ports/README.md b/Ports/README.md index b80454e5773..a5daef3e0e0 100644 --- a/Ports/README.md +++ b/Ports/README.md @@ -29,13 +29,13 @@ its dependencies, the required files that will be downloaded as well as configuration/compilation options, and some other things (see [Writing ports scripts](#writing-ports-scripts) for details). -- To install a certain port, `cd` into its directory and run `./package.sh` -- To install all available ports, run the `build_all.sh` script in this - directory. Pass `clean` as first argument to remove old build files - beforehand. -- To reinstall all currently installed ports, run the `build_installed.sh` - script in this directory. This is sometimes required when LibC changes, for - example. Pass `clean` as first argument to remove old build files beforehand. +- To install a certain port, `cd` into its directory and run `./package.sh` +- To install all available ports, run the `build_all.sh` script in this + directory. Pass `clean` as first argument to remove old build files + beforehand. +- To reinstall all currently installed ports, run the `build_installed.sh` + script in this directory. This is sometimes required when LibC changes, for + example. Pass `clean` as first argument to remove old build files beforehand. Installed ports are being tracked in `Build/x86_64/Root/usr/Ports/installed.db` (a simple text file). You can delete this file at any time, in fact it must be edited or removed @@ -104,12 +104,12 @@ file. Start a development session with guided patch importing. This mode has a bunch of nice features: -- Drops the user in a git repository backed by another (local) git repository - that acts as the "clean", patched version of the port that is ready to be built -- The "remote" repository can be pushed to, pulled from and generally anything that - you'd want to do with a remote repo. -- After leaving the dev shell, all patches are updated and the user will be prompted - whether they wish to generate a new patch readme file. +- Drops the user in a git repository backed by another (local) git repository + that acts as the "clean", patched version of the port that is ready to be built +- The "remote" repository can be pushed to, pulled from and generally anything that + you'd want to do with a remote repo. +- After leaving the dev shell, all patches are updated and the user will be prompted + whether they wish to generate a new patch readme file. This mode takes an extra `--no-depends` option, that if given, will cause the dependency fetch and build steps to be skipped. @@ -304,19 +304,19 @@ build() { The following can be overridden, the names should be self-explanatory as they mostly match the [available options](#options): -- `pre_fetch` -- `post_fetch` -- `pre_patch` -- `pre_configure` -- `configure` -- `post_configure` -- `build` -- `pre_install` -- `install` -- `post_install` -- `clean` -- `clean_dist` -- `clean_all` +- `pre_fetch` +- `post_fetch` +- `pre_patch` +- `pre_configure` +- `configure` +- `post_configure` +- `build` +- `pre_install` +- `install` +- `post_install` +- `clean` +- `clean_dist` +- `clean_all` A few (non-overridable) util functions are available as well: @@ -341,20 +341,20 @@ run_replace_in_file "s/define FOO 1/undef FOO/" config.h You can either: -- Add new ports - just get the software to build and add the necessary patches - and `package.sh` script -- Update an existing port: bumping its version, getting functionality to work - that wasn't available so far etc. Make sure to update the patches - accordingly. +- Add new ports - just get the software to build and add the necessary patches + and `package.sh` script +- Update an existing port: bumping its version, getting functionality to work + that wasn't available so far etc. Make sure to update the patches + accordingly. Some videos of Andreas adding new ports can be found on YouTube, they might help you understand how this usually works: -- [OS hacking: Porting the Bash shell](https://www.youtube.com/watch?v=QNK8vK-nkkg) - (2019-05-20) -- [OS hacking: Porting DOOM to Serenity](https://www.youtube.com/watch?v=a0P_bB6wjhY) - (2019-09-09) -- [OS hacking: Let's port git to SerenityOS!](https://www.youtube.com/watch?v=1-7VQwWo2Tg) - (2020-02-19) -- [OS hacking: Fixing a resize bug with the vim port](https://www.youtube.com/watch?v=d4uVnawzHdQ) - (2020-06-03) +- [OS hacking: Porting the Bash shell](https://www.youtube.com/watch?v=QNK8vK-nkkg) + (2019-05-20) +- [OS hacking: Porting DOOM to Serenity](https://www.youtube.com/watch?v=a0P_bB6wjhY) + (2019-09-09) +- [OS hacking: Let's port git to SerenityOS!](https://www.youtube.com/watch?v=1-7VQwWo2Tg) + (2020-02-19) +- [OS hacking: Fixing a resize bug with the vim port](https://www.youtube.com/watch?v=d4uVnawzHdQ) + (2020-06-03) diff --git a/Ports/openssh/ReadMe.md b/Ports/openssh/ReadMe.md index 49aaa9009ca..c33f09136b4 100644 --- a/Ports/openssh/ReadMe.md +++ b/Ports/openssh/ReadMe.md @@ -1,10 +1,11 @@ # Known limitations -- No SK/FIDO support. -- No DNS support. -- No proxy support. -- Assumes SSH2.0 for now. -- Cannot determine compatibility flags. - This means there may be some weird bugs when connecting to certain SSH implementations. + +- No SK/FIDO support. +- No DNS support. +- No proxy support. +- Assumes SSH2.0 for now. +- Cannot determine compatibility flags. + This means there may be some weird bugs when connecting to certain SSH implementations. # Autostart SSHD @@ -25,4 +26,4 @@ Arguments=-A KeepAlive=false SystemModes=text,graphical EOF -``` \ No newline at end of file +``` diff --git a/README.md b/README.md index 1eff95ab21c..6c755ec9d77 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ Roughly speaking, the goal is a marriage between the aesthetic of late-1990s pro You can watch videos of the system being developed on YouTube: -* [Andreas Kling's channel](https://youtube.com/andreaskling) -* [Linus Groh's channel](https://youtube.com/linusgroh) -* [kleines Filmröllchen's channel](https://www.youtube.com/c/kleinesfilmroellchen) +- [Andreas Kling's channel](https://youtube.com/andreaskling) +- [Linus Groh's channel](https://youtube.com/linusgroh) +- [kleines Filmröllchen's channel](https://www.youtube.com/c/kleinesfilmroellchen) ## Screenshot @@ -26,19 +26,19 @@ You can watch videos of the system being developed on YouTube: ## Features -* Modern x86 64-bit kernel with pre-emptive multi-threading -* [Browser](Userland/Applications/Browser/) with JavaScript, WebAssembly, and more (check the spec compliance for [JS](https://serenityos.github.io/libjs-website/test262/), [CSS](https://css.tobyase.de/), and [Wasm](https://serenityos.github.io/libjs-website/wasm/)) -* Security features (hardware protections, limited userland capabilities, W^X memory, `pledge` & `unveil`, (K)ASLR, OOM-resistance, web-content isolation, state-of-the-art TLS algorithms, ...) -* [System services](Userland/Services/) (WindowServer, LoginServer, AudioServer, WebServer, RequestServer, CrashServer, ...) and modern IPC -* Good POSIX compatibility ([LibC](Userland/Libraries/LibC/), Shell, syscalls, signals, pseudoterminals, filesystem notifications, standard Unix [utilities](Userland/Utilities/), ...) -* POSIX-like virtual file systems (/proc, /dev, /sys, /tmp, ...) and ext2 file system -* Network stack and applications with support for IPv4, TCP, UDP; DNS, HTTP, Gemini, IMAP, NTP -* Profiling, debugging and other development tools (Kernel-supported profiling, CrashReporter, interactive GUI playground, HexEditor, HackStudio IDE for C++ and more) -* [Libraries](Userland/Libraries/) for everything from cryptography to OpenGL, audio, JavaScript, GUI, playing chess, ... -* Support for many common and uncommon file formats (PNG, JPEG, GIF, MP3, WAV, FLAC, ZIP, TAR, PDF, QOI, Gemini, ...) -* Unified style and design philosophy, flexible theming system, [custom (bitmap and vector) fonts](https://fonts.serenityos.net/font-family) -* [Games](Userland/Games/) (Solitaire, Minesweeper, 2048, chess, Conway's Game of Life, ...) and [demos](Userland/Demos/) (CatDog, Starfield, Eyes, mandelbrot set, WidgetGallery, ...) -* Every-day GUI programs and utilities (Spreadsheet with JavaScript, TextEditor, Terminal, PixelPaint, various multimedia viewers and players, Mail, Assistant, Calculator, ...) +- Modern x86 64-bit kernel with pre-emptive multi-threading +- [Browser](Userland/Applications/Browser/) with JavaScript, WebAssembly, and more (check the spec compliance for [JS](https://serenityos.github.io/libjs-website/test262/), [CSS](https://css.tobyase.de/), and [Wasm](https://serenityos.github.io/libjs-website/wasm/)) +- Security features (hardware protections, limited userland capabilities, W^X memory, `pledge` & `unveil`, (K)ASLR, OOM-resistance, web-content isolation, state-of-the-art TLS algorithms, ...) +- [System services](Userland/Services/) (WindowServer, LoginServer, AudioServer, WebServer, RequestServer, CrashServer, ...) and modern IPC +- Good POSIX compatibility ([LibC](Userland/Libraries/LibC/), Shell, syscalls, signals, pseudoterminals, filesystem notifications, standard Unix [utilities](Userland/Utilities/), ...) +- POSIX-like virtual file systems (/proc, /dev, /sys, /tmp, ...) and ext2 file system +- Network stack and applications with support for IPv4, TCP, UDP; DNS, HTTP, Gemini, IMAP, NTP +- Profiling, debugging and other development tools (Kernel-supported profiling, CrashReporter, interactive GUI playground, HexEditor, HackStudio IDE for C++ and more) +- [Libraries](Userland/Libraries/) for everything from cryptography to OpenGL, audio, JavaScript, GUI, playing chess, ... +- Support for many common and uncommon file formats (PNG, JPEG, GIF, MP3, WAV, FLAC, ZIP, TAR, PDF, QOI, Gemini, ...) +- Unified style and design philosophy, flexible theming system, [custom (bitmap and vector) fonts](https://fonts.serenityos.net/font-family) +- [Games](Userland/Games/) (Solitaire, Minesweeper, 2048, chess, Conway's Game of Life, ...) and [demos](Userland/Demos/) (CatDog, Starfield, Eyes, mandelbrot set, WidgetGallery, ...) +- Every-day GUI programs and utilities (Spreadsheet with JavaScript, TextEditor, Terminal, PixelPaint, various multimedia viewers and players, Mail, Assistant, Calculator, ...) ... and all of the above are right in this repository, no extra dependencies, built from-scratch by us :^) @@ -56,7 +56,7 @@ Code-related documentation can be found in the [documentation](Documentation/) f See the [SerenityOS build instructions](https://github.com/SerenityOS/serenity/blob/master/Documentation/BuildInstructions.md) or the [Ladybird build instructions](Documentation/BuildInstructionsLadybird.md). -The build system supports a cross-compilation build of SerenityOS from Linux, macOS, Windows (with WSL2) and many other *Nixes. +The build system supports a cross-compilation build of SerenityOS from Linux, macOS, Windows (with WSL2) and many other \*Nixes. The default build system commands will launch a QEMU instance running the OS with hardware or software virtualization enabled as supported. @@ -72,73 +72,73 @@ A general guide for contributing can be found in [`CONTRIBUTING.md`](CONTRIBUTIN ## Authors -* **Andreas Kling** - [awesomekling](https://twitter.com/awesomekling) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/awesomekling) -* **Robin Burchell** - [rburchell](https://github.com/rburchell) -* **Conrad Pankoff** - [deoxxa](https://github.com/deoxxa) -* **Sergey Bugaev** - [bugaevc](https://github.com/bugaevc) -* **Liav A** - [supercomputer7](https://github.com/supercomputer7) -* **Linus Groh** - [linusg](https://github.com/linusg) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/linusg) -* **Ali Mohammad Pur** - [alimpfard](https://github.com/alimpfard) -* **Shannon Booth** - [shannonbooth](https://github.com/shannonbooth) -* **Hüseyin ASLITÜRK** - [asliturk](https://github.com/asliturk) -* **Matthew Olsson** - [mattco98](https://github.com/mattco98) -* **Nico Weber** - [nico](https://github.com/nico) -* **Brian Gianforcaro** - [bgianfo](https://github.com/bgianfo) -* **Ben Wiederhake** - [BenWiederhake](https://github.com/BenWiederhake) -* **Tom** - [tomuta](https://github.com/tomuta) -* **Paul Scharnofske** - [asynts](https://github.com/asynts) -* **Itamar Shenhar** - [itamar8910](https://github.com/itamar8910) -* **Luke Wilde** - [Lubrsi](https://github.com/Lubrsi) -* **Brendan Coles** - [bcoles](https://github.com/bcoles) -* **Andrew Kaster** - [ADKaster](https://github.com/ADKaster) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ADKaster) -* **thankyouverycool** - [thankyouverycool](https://github.com/thankyouverycool) -* **Idan Horowitz** - [IdanHo](https://github.com/IdanHo) -* **Gunnar Beutner** - [gunnarbeutner](https://github.com/gunnarbeutner) -* **Tim Flynn** - [trflynn89](https://github.com/trflynn89) -* **Jean-Baptiste Boric** - [boricj](https://github.com/boricj) -* **Stephan Unverwerth** - [sunverwerth](https://github.com/sunverwerth) -* **Max Wipfli** - [MaxWipfli](https://github.com/MaxWipfli) -* **Daniel Bertalan** - [BertalanD](https://github.com/BertalanD) -* **Jelle Raaijmakers** - [GMTA](https://github.com/GMTA) -* **Sam Atkins** - [AtkinsSJ](https://github.com/AtkinsSJ) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/AtkinsSJ) -* **Tobias Christiansen** - [TobyAsE](https://github.com/TobyAsE) -* **Lenny Maiorani** - [ldm5180](https://github.com/ldm5180) -* **sin-ack** - [sin-ack](https://github.com/sin-ack) -* **Jesse Buhagiar** - [Quaker762](https://github.com/Quaker762) -* **Peter Elliott** - [Petelliott](https://github.com/Petelliott) -* **Karol Kosek** - [krkk](https://github.com/krkk) -* **Mustafa Quraish** - [mustafaquraish](https://github.com/mustafaquraish) -* **David Tuin** - [davidot](https://github.com/davidot) -* **Leon Albrecht** - [Hendiadyoin1](https://github.com/Hendiadyoin1) -* **Tim Schumacher** - [timschumi](https://github.com/timschumi) -* **Marcus Nilsson** - [metmo](https://github.com/metmo) -* **Gegga Thor** - [Xexxa](https://github.com/Xexxa) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/Xexxa) -* **kleines Filmröllchen** - [kleinesfilmroellchen](https://github.com/kleinesfilmroellchen) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/kleinesfilmroellchen) -* **Kenneth Myhra** - [kennethmyhra](https://github.com/kennethmyhra) -* **Maciej** - [sppmacd](https://github.com/sppmacd) -* **Sahan Fernando** - [ccapitalK](https://github.com/ccapitalK) -* **Benjamin Maxwell** - [MacDue](https://github.com/MacDue) -* **Dennis Esternon** - [djwisdom](https://github.com/djwisdom) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/djwisdom) -* **frhun** - [frhun](https://github.com/frhun) -* **networkException** - [networkException](https://github.com/networkException) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/networkException) -* **Brandon Jordan** - [electrikmilk](https://github.com/electrikmilk) -* **Lucas Chollet** - [LucasChollet](https://github.com/LucasChollet) -* **Timon Kruiper** - [FireFox317](https://github.com/FireFox317) -* **Martin Falisse** - [martinfalisse](https://github.com/martinfalisse) -* **Gregory Bertilson** - [Zaggy1024](https://github.com/Zaggy1024) -* **Erik Wouters** - [EWouters](https://github.com/EWouters) -* **Rodrigo Tobar** - [rtobar](https://github.com/rtobar) -* **Alexander Kalenik** - [kalenikaliaksandr](https://github.com/kalenikaliaksandr) -* **Tim Ledbetter** - [tcl3](https://github.com/tcl3) -* **Steffen T. Larssen** - [stelar7](https://github.com/stelar7) -* **Andi Gallo** - [axgallo](https://github.com/axgallo) -* **Simon Wanner** - [skyrising](https://github.com/skyrising) -* **FalseHonesty** - [FalseHonesty](https://github.com/FalseHonesty) -* **Bastiaan van der Plaat** - [bplaat](https://github.com/bplaat) -* **Dan Klishch** - [DanShaders](https://github.com/DanShaders) -* **Julian Offenhäuser** - [janso3](https://github.com/janso3) -* **Sönke Holz** - [spholz](https://github.com/spholz) -* **implicitfield** - [implicitfield](https://github.com/implicitfield) +- **Andreas Kling** - [awesomekling](https://twitter.com/awesomekling) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/awesomekling) +- **Robin Burchell** - [rburchell](https://github.com/rburchell) +- **Conrad Pankoff** - [deoxxa](https://github.com/deoxxa) +- **Sergey Bugaev** - [bugaevc](https://github.com/bugaevc) +- **Liav A** - [supercomputer7](https://github.com/supercomputer7) +- **Linus Groh** - [linusg](https://github.com/linusg) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/linusg) +- **Ali Mohammad Pur** - [alimpfard](https://github.com/alimpfard) +- **Shannon Booth** - [shannonbooth](https://github.com/shannonbooth) +- **Hüseyin ASLITÜRK** - [asliturk](https://github.com/asliturk) +- **Matthew Olsson** - [mattco98](https://github.com/mattco98) +- **Nico Weber** - [nico](https://github.com/nico) +- **Brian Gianforcaro** - [bgianfo](https://github.com/bgianfo) +- **Ben Wiederhake** - [BenWiederhake](https://github.com/BenWiederhake) +- **Tom** - [tomuta](https://github.com/tomuta) +- **Paul Scharnofske** - [asynts](https://github.com/asynts) +- **Itamar Shenhar** - [itamar8910](https://github.com/itamar8910) +- **Luke Wilde** - [Lubrsi](https://github.com/Lubrsi) +- **Brendan Coles** - [bcoles](https://github.com/bcoles) +- **Andrew Kaster** - [ADKaster](https://github.com/ADKaster) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ADKaster) +- **thankyouverycool** - [thankyouverycool](https://github.com/thankyouverycool) +- **Idan Horowitz** - [IdanHo](https://github.com/IdanHo) +- **Gunnar Beutner** - [gunnarbeutner](https://github.com/gunnarbeutner) +- **Tim Flynn** - [trflynn89](https://github.com/trflynn89) +- **Jean-Baptiste Boric** - [boricj](https://github.com/boricj) +- **Stephan Unverwerth** - [sunverwerth](https://github.com/sunverwerth) +- **Max Wipfli** - [MaxWipfli](https://github.com/MaxWipfli) +- **Daniel Bertalan** - [BertalanD](https://github.com/BertalanD) +- **Jelle Raaijmakers** - [GMTA](https://github.com/GMTA) +- **Sam Atkins** - [AtkinsSJ](https://github.com/AtkinsSJ) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/AtkinsSJ) +- **Tobias Christiansen** - [TobyAsE](https://github.com/TobyAsE) +- **Lenny Maiorani** - [ldm5180](https://github.com/ldm5180) +- **sin-ack** - [sin-ack](https://github.com/sin-ack) +- **Jesse Buhagiar** - [Quaker762](https://github.com/Quaker762) +- **Peter Elliott** - [Petelliott](https://github.com/Petelliott) +- **Karol Kosek** - [krkk](https://github.com/krkk) +- **Mustafa Quraish** - [mustafaquraish](https://github.com/mustafaquraish) +- **David Tuin** - [davidot](https://github.com/davidot) +- **Leon Albrecht** - [Hendiadyoin1](https://github.com/Hendiadyoin1) +- **Tim Schumacher** - [timschumi](https://github.com/timschumi) +- **Marcus Nilsson** - [metmo](https://github.com/metmo) +- **Gegga Thor** - [Xexxa](https://github.com/Xexxa) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/Xexxa) +- **kleines Filmröllchen** - [kleinesfilmroellchen](https://github.com/kleinesfilmroellchen) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/kleinesfilmroellchen) +- **Kenneth Myhra** - [kennethmyhra](https://github.com/kennethmyhra) +- **Maciej** - [sppmacd](https://github.com/sppmacd) +- **Sahan Fernando** - [ccapitalK](https://github.com/ccapitalK) +- **Benjamin Maxwell** - [MacDue](https://github.com/MacDue) +- **Dennis Esternon** - [djwisdom](https://github.com/djwisdom) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/djwisdom) +- **frhun** - [frhun](https://github.com/frhun) +- **networkException** - [networkException](https://github.com/networkException) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/networkException) +- **Brandon Jordan** - [electrikmilk](https://github.com/electrikmilk) +- **Lucas Chollet** - [LucasChollet](https://github.com/LucasChollet) +- **Timon Kruiper** - [FireFox317](https://github.com/FireFox317) +- **Martin Falisse** - [martinfalisse](https://github.com/martinfalisse) +- **Gregory Bertilson** - [Zaggy1024](https://github.com/Zaggy1024) +- **Erik Wouters** - [EWouters](https://github.com/EWouters) +- **Rodrigo Tobar** - [rtobar](https://github.com/rtobar) +- **Alexander Kalenik** - [kalenikaliaksandr](https://github.com/kalenikaliaksandr) +- **Tim Ledbetter** - [tcl3](https://github.com/tcl3) +- **Steffen T. Larssen** - [stelar7](https://github.com/stelar7) +- **Andi Gallo** - [axgallo](https://github.com/axgallo) +- **Simon Wanner** - [skyrising](https://github.com/skyrising) +- **FalseHonesty** - [FalseHonesty](https://github.com/FalseHonesty) +- **Bastiaan van der Plaat** - [bplaat](https://github.com/bplaat) +- **Dan Klishch** - [DanShaders](https://github.com/DanShaders) +- **Julian Offenhäuser** - [janso3](https://github.com/janso3) +- **Sönke Holz** - [spholz](https://github.com/spholz) +- **implicitfield** - [implicitfield](https://github.com/implicitfield) And many more! [See here](https://github.com/SerenityOS/serenity/graphs/contributors) for a full contributor list. The people listed above have landed more than 100 commits in the project. :^) diff --git a/Userland/Libraries/LibTest/Randomized/README.md b/Userland/Libraries/LibTest/Randomized/README.md index 7fab5aec4e5..7e0b9f8a8d3 100644 --- a/Userland/Libraries/LibTest/Randomized/README.md +++ b/Userland/Libraries/LibTest/Randomized/README.md @@ -59,7 +59,7 @@ talk: https://www.youtube.com/watch?v=WE5bmt0zBxg) On a very high level, the PBT runner remembers the random bits (`RandomRun`) used when generating the random value, and when it finds a value that fails the user's test, instead of trying to shrink the generated value it tries to shrink -these random bits and then generate a new value from them. +these random bits and then generate a new value from them. This makes shrinking work automatically on any data you might want to generate. @@ -74,46 +74,53 @@ the user. ## Code organization -- `TestResult.h` - - Defines an enum class TestResult. - This expands the typical "passed / failed": we also need to care about - a generator rejecting a RandomRun (eg. when the user calls the ASSUME(...) - macro with a predicate that can't be satisfied). +- `TestResult.h` -- `Generator.h` - - Contains generators: fns of shape T(), eg. `u32 Gen::unsigned_int(u32 max)` - - These implicitly depend on a RandomnessSource held by the singleton - TestSuite. - - These can be called directly, but the top-level use by the user should always - happen via the GEN(...) macro which makes sure the generated value gets - logged to the user in case of a failure. - - Example: - `Gen::vector(1, 4, []() { return Gen::unsigned_int(5); })` - generates vectors of length between 1 and 4, of unsigned ints in range 0..5. - Eg. `{2,5,3}`, `{0}`, `{1,5,5,2}`. + - Defines an enum class TestResult. + This expands the typical "passed / failed": we also need to care about + a generator rejecting a RandomRun (eg. when the user calls the ASSUME(...) + macro with a predicate that can't be satisfied). -- `RandomnessSource.h` - - A source of random bits. - - There are two variants of `RandomnessSource`: - - Live: gives `AK/Random` u32 values and remembers them into a `RandomRun` - - Recorded: gives (replays) u32 values from a static `RandomRun` +- `Generator.h` -- `RandomRun.h` - - A finite sequence of random bits (in practice, `u32`s). - - Example: `{2,5,0,11,8,0,0,1}` + - Contains generators: fns of shape T(), eg. `u32 Gen::unsigned_int(u32 max)` + - These implicitly depend on a RandomnessSource held by the singleton + TestSuite. + - These can be called directly, but the top-level use by the user should always + happen via the GEN(...) macro which makes sure the generated value gets + logged to the user in case of a failure. + - Example: + `Gen::vector(1, 4, []() { return Gen::unsigned_int(5); })` + generates vectors of length between 1 and 4, of unsigned ints in range 0..5. + Eg. `{2,5,3}`, `{0}`, `{1,5,5,2}`. -- `ShrinkCommand.h` - - A high-level recipe for how to try and minimize a given `RandomRun`. - - For example, "zero this contiguous chunk of it" or "minimize the number on - this index using binary search". - - These later get interpreted by the PBT runner on a specific `RandomRun`. +- `RandomnessSource.h` -- `Chunk.h` - - A description of a contiguous `RandomRun` slice. - - Example: `Chunk{size = 4, index = 2}`: [_,_,X,X,X,X,...] + - A source of random bits. + - There are two variants of `RandomnessSource`: + - Live: gives `AK/Random` u32 values and remembers them into a `RandomRun` + - Recorded: gives (replays) u32 values from a static `RandomRun` -- `Shrink.h` - - Algorithms for interpreting `ShrinkCommand`s and the main shrinking loop +- `RandomRun.h` -- `TestCase.h` - - The `TestCase::randomized(...)` function contains the main testing loop + - A finite sequence of random bits (in practice, `u32`s). + - Example: `{2,5,0,11,8,0,0,1}` + +- `ShrinkCommand.h` + + - A high-level recipe for how to try and minimize a given `RandomRun`. + - For example, "zero this contiguous chunk of it" or "minimize the number on + this index using binary search". + - These later get interpreted by the PBT runner on a specific `RandomRun`. + +- `Chunk.h` + + - A description of a contiguous `RandomRun` slice. + - Example: `Chunk{size = 4, index = 2}`: [_,_,X,X,X,X,...] + +- `Shrink.h` + + - Algorithms for interpreting `ShrinkCommand`s and the main shrinking loop + +- `TestCase.h` + - The `TestCase::randomized(...)` function contains the main testing loop