From 11227cb445ffeed8f8c75153f33510f91c402298 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 17 Sep 2025 15:21:07 +0000 Subject: [PATCH] Fix typos and grammatical errors in documentation and comments. This commit corrects a wide range of typos and grammatical errors across many documentation files, including the main markdown files, files in the doc/ directory, and man pages in the binrz/man/ directory. It also fixes some misspellings found in source code comments. These changes improve the readability and professionalism of the documentation. --- BUILDING.md | 172 +++++++++--------- CONTRIBUTING.md | 68 +++---- DEVELOPERS.md | 206 ++++++++++++---------- README.md | 34 ++-- binrz/man/rizin.1 | 136 +++++++------- binrz/man/rz-asm.1 | 130 +++++++------- binrz/man/rz-ax.1 | 70 ++++---- binrz/man/rz-bin.1 | 154 ++++++++-------- binrz/man/rz-diff.1 | 78 ++++---- binrz/man/rz-esil.7 | 16 +- binrz/man/rz-find.1 | 52 +++--- binrz/man/rz-gg.1 | 76 ++++---- binrz/man/rz-hash.1 | 58 +++--- binrz/man/rz-run.1 | 122 ++++++------- binrz/man/rz-sign.1 | 15 +- binrz/man/rz-test.1 | 46 ++--- doc/PACKAGERS.md | 115 ++++++------ doc/RELEASE.md | 23 +-- doc/asm_strings.md | 68 +++---- doc/avr.md | 12 +- doc/brainfuck.md | 25 +-- doc/calling-conventions.md | 55 ++++-- doc/crosscompile.md | 14 +- doc/debug-internals.md | 125 ++++++------- doc/debug.md | 14 +- doc/flirt.md | 49 ++--- doc/gdb.md | 61 ++++--- doc/register_profile.md | 14 +- doc/release-template.md | 38 ++-- doc/rzil.md | 175 +++++++++--------- doc/rzshell.md | 92 +++++----- doc/siol.md | 45 +++-- doc/windbg.md | 42 ++--- librz/arch/isa/arm/arm_il32.c | 2 +- librz/include/rz_util/rz_annotated_code.h | 2 +- librz/io/io.c | 2 +- librz/sign/flirt.c | 2 +- librz/util/sdb/src/cdb.c | 2 +- subprojects/rzar/ar.c | 2 +- test/unit/test_str.c | 2 +- test/unit/test_strbuf.c | 4 +- 41 files changed, 1244 insertions(+), 1174 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index b36b7168208..93250dcc744 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,6 +1,6 @@ # Clone the Rizin project and keep it updated -The first time you download Rizin you can use: +When you download Rizin for the first time, you can use: ``` $ git clone https://github.com/rizinorg/rizin ``` @@ -9,25 +9,29 @@ After that, use `git pull` to update the Rizin codebase. # Build -Rizin uses [`meson`](https://mesonbuild.com/) to build. As not all systems have -a version of `meson` that is recent enough, we suggest to install it directly +Rizin uses [`meson`](https://mesonbuild.com/) to build. Since not all systems have +a version of `meson` that is recent enough, we suggest installing it directly from `pip` with `pip install meson`. If necessary, also install `ninja` with `pip install ninja`. -If you are trying to build Rizin to create a package for a distribution, -take a look at [doc/PACKAGERS.md][]. +If you are building Rizin to create a package for a distribution, +see [doc/PACKAGERS.md][]. ## Note about debugging -Unless you are interested in debugging Rizin, it is a good idea to pass the `--buildtype=release` flag to `meson` for increased performance and to prevent the buggy `mspdbsrv.exe` process from [blocking/breaking the building process](https://social.msdn.microsoft.com/Forums/en-US/9e58b7d1-a47d-4a76-943a-4f35090616e8/link-fatal-error-lnk1318?forum=vclanguage) when generating `PDB` files in Windows. See the first table in the [Running Meson Documentation](https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory) for other build types. +Unless you are interested in debugging Rizin, it is a good idea to pass the +`--buildtype=release` flag to `meson` for increased performance and to prevent +the buggy `mspdbsrv.exe` process from blocking or breaking the build process +when generating `PDB` files on Windows. See the first table in the +[Running Meson Documentation](https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory) for other build types. ## *NIX systems ### Build system-wide, in `/usr/local` -This is the default configuration and it allows you to install your built Rizin -version while keeping, if provided, the Rizin version shipped by your -distribution in `/usr`. +This is the default configuration, which allows you to install your built +version of Rizin while keeping the version shipped by your distribution in +`/usr` (if present). ``` $ meson --buildtype=release build @@ -35,19 +39,18 @@ $ ninja -C build # or `meson compile -C build` $ sudo ninja -C build install # or `sudo meson install -C build` ``` -NOTE: when `--prefix=/usr` is not used, meson will set `RPATH` to ensure that +NOTE: When `--prefix=/usr` is not used, `meson` sets `RPATH` to ensure that libraries can be found on the system without having to deal with -`LD_LIBRARY_PATH` or ld settings. This is done to ensure a simple -installation process out-of-the-box, but if you don't want this behaviour and -you know what you are doing, you can still use `-Dlocal=disabled` to avoid -using `RPATH`. +`LD_LIBRARY_PATH` or `ld` settings. This is done to ensure a simple +out-of-the-box installation process. However, if you do not want this +behavior and you know what you are doing, you can use `-Dlocal=disabled` to +avoid using `RPATH`. ### Build system-wide, in `/usr` -If your system does not already provide rizin in `/usr/bin`, you want to package -Rizin on your preferred distribution or you just prefer to have Rizin together -with all other binaries on your system, you can also install it system-wide in -`/usr`. +If your system does not already provide Rizin in `/usr/bin`, and you want to +package Rizin for your preferred distribution or simply prefer to have Rizin +with all other system binaries, you can install it system-wide in `/usr`. ``` $ meson --buildtype=release --prefix=/usr build @@ -55,16 +58,16 @@ $ ninja -C build $ sudo ninja -C build install ``` -This kind of installation is not recommended if your system provides Rizin as -a package or if you don't want to mess with software provided by your -distribution. +This type of installation is not recommended if your system already provides +Rizin as a package or if you do not want to interfere with software provided +by your distribution. ### Build user-wide, in `~/.local` -You are not forced to install Rizin in your system, you can just make it -available for your current user, without requiring you to have `sudo` access to -the machine (or if you don't trust our build scripts enough). +You are not required to install Rizin system-wide; you can make it +available only for your current user. This does not require `sudo` access +(and is a good option if you don't fully trust our build scripts). ``` $ meson --buildtype=release --prefix=~/.local build @@ -72,23 +75,23 @@ $ ninja -C build $ ninja -C build install ``` -The `install` step will install rizin in `~/.local/bin`, so make sure to add it -to your `PATH` variable (e.g. `export PATH=$PATH:~/.local/bin`). +The `install` step will install Rizin in `~/.local/bin`, so make sure to add +it to your `PATH` variable (e.g., `export PATH=$PATH:~/.local/bin`). -NOTE: meson will set `RPATH` to ensure that libraries can be found on the -system without having to deal with `LD_LIBRARY_PATH` or ld settings. This is -done to ensure a simple installation process out-of-the-box, but if you don't -want this behaviour and you know what you are doing, you can still use -`-Dlocal=disabled` to avoid using `RPATH`. +NOTE: `meson` sets `RPATH` to ensure that libraries can be found on the +system without having to deal with `LD_LIBRARY_PATH` or `ld` settings. This +is done to ensure a simple out-of-the-box installation process. However, if +you do not want this behavior and you know what you are doing, you can still +use `-Dlocal=disabled` to avoid using `RPATH`. ## Windows -The building steps on Windows are the same as on *NIX systems, however you +The build steps on Windows are the same as on *NIX systems; however, you will have to run the following commands from the Visual Studio Developer -shell (search for "x64 Native Tools Command Prompt for VS 2019" or similar). -To install Meson on Windows, follow instructions -[here](https://mesonbuild.com/Getting-meson.html). If using PowerShell, -replace `%CD%` with `$((Get-Item .).FullName)` +shell (e.g., search for "x64 Native Tools Command Prompt for VS 2019"). +To install Meson on Windows, follow the instructions +[here](https://mesonbuild.com/Getting-meson.html). If you are using PowerShell, +replace `%CD%` with `$((Get-Item .).FullName)`. ``` $ meson --buildtype=release --prefix=%CD%\rizin-install build @@ -96,8 +99,8 @@ $ ninja -C build $ ninja -C build install ``` -You can run rizin from `.\rizin-install\bin`. If you don't specify any -`--prefix`, meson will install rizin directly under `C:\`. +You can run Rizin from `.\rizin-install\bin`. If you don't specify any +`--prefix`, `meson` will install Rizin directly in `C:\`. ## Build with ASAN/UBSAN @@ -108,12 +111,12 @@ $ meson --buildtype=release -Db_sanitize=address,undefined build ``` *Note*: Due to [a bug](https://github.com/google/sanitizers/issues/1716) in ASAN, -ASAN built binaries will crash or endlessly loop randomly, and only report +binaries built with ASAN may crash or loop endlessly, reporting only `AddressSanitizer:DEADLYSIGNAL`. -This also effects the build of Rizin, because we run an ASAN compiled binary (`sdb`) -during the build. -If this binary stays in an endless loop of `AddressSanitizer:DEADLYSIGNAL`, -the build will hang up and fill up your memory. +This also affects the Rizin build, because we run an ASAN-compiled binary (`sdb`) +during the build process. +If this binary enters an endless loop of `AddressSanitizer:DEADLYSIGNAL`, +the build will hang and consume all available memory. To fix this, you need to lower the size of the random offset applied to VMA base addresses with: @@ -124,9 +127,9 @@ sudo sysctl vm.mmap_rnd_bits=28 ## Build fully-static binaries -It may be useful to run Rizin just by using a single file, which can be -copied on other systems if necessary. On *NIX systems, this adds the classic -`-static` flag to the linker, while on Windows it uses `/MT`. +It may be useful to run Rizin from a single file, which can be copied to +other systems if necessary. On *NIX systems, this adds the `-static` flag +to the linker, while on Windows, it uses `/MT`. ``` $ meson --buildtype=release --default-library=static -Dstatic_runtime=true build @@ -140,21 +143,21 @@ Use `-Db_coverage=true` during the setup phase. $ meson -Db_coverage=true --buildtype=debug build ``` -Run the command you need the coverage for. +Run the command for which you need coverage. ```sh # For example the ARM asm tests rz-test test/db/asm/arm* ``` -Generate the coverage report as HTML with `gcovr`. +Generate an HTML coverage report with `gcovr`. ```bash -# Install gcovr via pip or any other way +# Install `gcovr` via `pip` or another method. pip install gcovr mkdir cov_report cd cov_report -# Generate coverage report for each directory and file +# Generate a coverage report for each directory and file gcovr -r .. --html-nested coverage.html ``` @@ -162,22 +165,22 @@ Open `coverage.html` in your browser and explore. ## Cross-compilation for Android -You can cross-compile rizin from your main machine to target your Android +You can cross-compile Rizin from your main machine to target an Android device. First download and install the Android NDK from [https://developer.android.com/ndk](https://developer.android.com/ndk). -Then you can use meson to cross-compile, however you have to provide a -configuration file that specifies all the necessary information meson needs to -know to correctly cross-compile. +You can then use `meson` to cross-compile; however, you must provide a +configuration file that specifies all the necessary information for `meson` +to cross-compile correctly. You can find an [example](https://github.com/rizinorg/rizin/blob/dev/.github/meson-android-aarch64.ini) of such a file in our codebase, but you should adjust it to match your system. -To make the deployment and usage of the rizin tools easier from within your -Android device, we suggest to compile statically and by using the *blob* -feature, which will produce just one executable and link all the other tools to -that only tool, similar to how busybox works. +To simplify the deployment and usage of the Rizin tools on your Android +device, we suggest compiling statically and using the *blob* feature. This +will produce a single executable and link all other tools to it, similar to +how BusyBox works. ``` $ meson --buildtype release --default-library static --prefix=/tmp/android-dir -Dblob=true build -Dstatic_runtime=true --cross-file ./cross-compile-conf.ini @@ -185,18 +188,17 @@ $ ninja -C build $ ninja -C build install ``` -At this point you can find everything under `/tmp/android-dir` and you can copy -files to your Android device. +At this point, you can find everything under `/tmp/android-dir` and you can copy +the files to your Android device. ## Compile 32-bit Rizin on 64-bit machine -Whenever you want to build Rizin for a different system/architecture than the -one you are using for building, you are effectively cross-compiling and you -should provide a full configuration file to tell meson what is the target -machine. +Whenever you want to build Rizin for a different system or architecture than +the one you are using for the build, you are effectively cross-compiling and +must provide a full configuration file to tell `meson` the target machine. -Even to compile a 32-bit version of Rizin on a 64-bit machine, you should use -a configuration file like the following: +Even when compiling a 32-bit version of Rizin on a 64-bit machine, you +should use a configuration file like the following: ``` [binaries] @@ -220,8 +222,8 @@ cpu = 'i686' endian = 'little' ``` -Alternatively, if your distribution provide specific compiler tools for the -i686 architecture, you can use a configuration similar to this: +Alternatively, if your distribution provides specific compiler tools for the +i686 architecture, you can use a configuration similar to this one: ``` [binaries] @@ -238,9 +240,9 @@ cpu = 'i686' endian = 'little' ``` -Of course, you might have to adjust some settings depending on your system -and you should double check that you have installed all the necessary 32-bit -libraries and tools. Once you have checked everything, you can setup the +Of course, you may need to adjust some settings depending on your system, +and you should double-check that you have installed all the necessary 32-bit +libraries and tools. Once you have checked everything, you can set up the build directory with: ``` @@ -249,33 +251,33 @@ $ meson build --cross-file ./rizin-i386.ini # Uninstall -If Rizin was installed using `meson`, you can run the following command from the -same build directory where you had previously installed Rizin: +If Rizin was installed using `meson`, you can run the following command from +the same build directory where you previously installed it: ``` -$ sudo ninja -C uninstall # `sudo` may not be required based on how you configured the `build` directory with meson the first time``` +$ sudo ninja -C uninstall # `sudo` may not be required, depending on how you configured the `build` directory with `meson` the first time ``` -Furthermore, if you had installed Rizin using a distribution package, use the -corresponding package manager's method for removing a package to uninstall Rizin. +Furthermore, if you installed Rizin using a distribution package, use the +corresponding package manager's method to uninstall it. # Update Firstly, use `git pull` to update the Rizin codebase to the latest version. -To re-build Rizin after you have updated your source code, you can use: +To rebuild Rizin after updating your source code, you can use: ``` $ ninja -C build # or `meson compile -C build` -$ sudo ninja -C build install # or `sudo meson install -C build`. `sudo` may not be required based on how you configured the `build` directory with meson the first time +$ sudo ninja -C build install # or `sudo meson install -C build`. `sudo` may not be required, depending on how you configured the `build` directory with `meson` the first time ``` -If you are a developer, it might not be necessary to run the `install` step -(the second step from above) every time you build Rizin. You can directly use -`rizin` from `./build/binrz/rizin/rizin.` +If you are a developer, it may not be necessary to run the `install` step +(the second step from above) every time you build Rizin. You can use `rizin` +directly from `./build/binrz/rizin/rizin`. -If you encounter issues while re-building Rizin, try to remove the existing -build directory (e.g. `rm -r ./build`) and clean the subproject files -downloaded by meson (e.g. `git clean -dxff subprojects/`). Note that changing -a `meson.build` file does *not* guarantee a full rebuild. +If you encounter issues while rebuilding Rizin, try removing the existing +build directory (e.g., `rm -r ./build`) and cleaning the subproject files +downloaded by `meson` (e.g., `git clean -dxff subprojects/`). Note that +changing a `meson.build` file does *not* guarantee a full rebuild. [doc/PACKAGERS.md]: https://github.com/rizinorg/rizin/blob/dev/doc/PACKAGERS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 81f76d073a2..ab9c096781b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,43 +1,44 @@ # How to report issues -Before reporting an issue with GitHub, be sure that: -* You are using the latest released version of Rizin or the latest git version +Before reporting an issue on GitHub, ensure that: +* You are using the latest released version of Rizin or the latest version from git. * You are using a clean installation -* The issue was not already reported +* The issue has not already been reported -When the above conditions are satisfied, feel free to submit an issue while -trying to be as precise as possible. If you can, provide the problematic binary, -the steps to reproduce the error and a backtrace in case of SEGFAULTs. Try to -follow the issue template that comes by default. Any information will help to -fix the problem. +When the above conditions are met, feel free to submit an issue, trying to +be as precise as possible. If possible, provide the problematic binary, the +steps to reproduce the error, and a backtrace in case of a `SEGFAULT`. Try to +follow the default issue template. Any information will help fix the +problem. # How to contribute -There are a few guidelines that we need contributors to follow so that we can -try to keep the codebase consistent and clean. +There are a few guidelines that we ask contributors to follow to keep the +codebase consistent and clean. ## Getting Started -* Make sure you have a GitHub account and solid ability to use `git`. +* Make sure you have a GitHub account and a solid understanding of `git`. * Fork the repository on GitHub. * Create a topic branch from `dev`. Please avoid working directly on the `dev` branch. * Make commits of logical units. -* Be sure to follow the CODINGSTYLE (more on this in [DEVELOPERS.md][]). -* Submit the Pull Request(PR) on Github. -* When relevant, write a test in [test/](test). +* Be sure to follow the coding style (more on this in [DEVELOPERS.md][]). +* Submit a Pull Request (PR) on GitHub. +* When relevant, write a test in the `test/` directory. ## Rebasing onto updated dev -Every so often, your PR will lag behind `dev` and get conflicts. +Occasionally, your PR will lag behind `dev` and have merge conflicts. -To "update" your branch `my-awesome-feature`, you *rebase* it onto -the latest `rizinorg/dev`, and *force-push* the result into your fork. +To update your branch (e.g., `my-awesome-feature`), you must *rebase* it +onto the latest `rizinorg/dev` and then *force-push* the result to your +fork. #### Step 1: Switch to `dev` branch. ```sh $ git checkout dev ``` -#### Step 2: Pull new commits published to rizinorg repo. +#### Step 2: Pull new commits published to the `rizinorg` repo. ```sh $ git pull https://github.com/rizinorg/rizin ``` @@ -54,30 +55,31 @@ to `squash` your commits all into one, reorder, reword them, etc. ```sh $ git rebase -i dev ``` -Follow git instructions when conflicts arise. +Follow the `git` instructions when conflicts arise. #### Step 5: Publish your updated local branch. ```sh $ git push -f ``` -This `-f` *force-flag* is needed because git commits are immutable: rebasing -creates newer versions of them. git needs to confirm the destruction of -previous incarnations. +The `-f` (force) flag is needed because `git` commits are immutable; +rebasing creates new versions of them. Git needs confirmation to destroy +the previous versions. -When afraid to touch force and risk losing your work (do backups!..), -try *merging dev into your branch* instead of rebasing onto it. -This is discouraged, as it produces ugly hard-to-maintain commit history. +If you are afraid to use `--force` and risk losing your work (do +backups!), try *merging `dev` into your branch* instead of rebasing onto +it. This is discouraged, as it produces an ugly and hard-to-maintain +commit history. ## Commit message rules -When committing your changes into the repository you may want to follow some -rules to make the git history more readable and consistent: +When committing your changes to the repository, please follow these rules +to make the `git` history more readable and consistent: -* Start the message capitalized (only the first character must be in uppercase) -* Be short and concise, the whole concept must fit one line -* If a command is inlined, use backticks -* For extra details, add an empty line and use asterisk item list below -* Use present simple grammar tense (Add vs Added, Fix vs Fixed/Fixes) +* Capitalize the first letter of the commit message. +* Be short and concise; the entire concept must fit on one line. +* If a command is inlined, use backticks. +* For extra details, add an empty line and use an asterisk-based list below. +* Use the present tense (e.g., 'Add' instead of 'Added', 'Fix' instead of 'Fixed' or 'Fixes'). # Additional resources @@ -87,5 +89,5 @@ rules to make the git history more readable and consistent: [README.md]: https://github.com/rizinorg/rizin/blob/dev/README.md [DEVELOPERS.md]: https://github.com/rizinorg/rizin/blob/dev/DEVELOPERS.md -If you need more confidence in your git skills, check out this quick guide: +If you need more confidence in your `git` skills, check out this quick guide: diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 89467bf82d9..9e0c6048241 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -1,16 +1,16 @@ # DEVELOPERS -This file is aimed at developers who want to work on the Rizin code base. +This file is for developers who want to work on the Rizin codebase. ## Documentation -There is support for Doxygen document generation in this repo. -By running `doxygen` in the root of this repository, it will autodetect the +This repository supports Doxygen document generation. +Running `doxygen` in the root of this repository will autodetect the Doxyfile and generate HTML documentation into [doc/doxygen/html/index.html](./doc/doxygen/html/index.html). -If you're contributing code or willing to update existing code, you should use the -doxygen C-style comments to improve documentation and comments in code. +If you're contributing code or updating existing code, you should use +Doxygen C-style comments to improve documentation and comments in code. See the [Doxygen Manual](http://www.doxygen.nl/manual/index.html) for more info. Example usage can be found [here](http://www.doxygen.nl/manual/docblocks.html). @@ -32,7 +32,7 @@ Documentation goes into the source files (not the header files). static int find_min_max(RzList *maps, ut64 *min, ut64 *max, int skip, int width) { /* ... */ } ``` -In order to improve the documentation and help newcomers, documenting code is mandatory. +To improve the documentation and help newcomers, documenting code is mandatory. You should add or update the documentation of: - code written by you. @@ -48,8 +48,8 @@ E.g.: `Bug fix did not change the general behavior of the function. No documenta ### C -In order to contribute with patches or plugins, we encourage you to use the same -coding style as the rest of the code base. +To contribute with patches or plugins, we encourage you to use the same +coding style as the rest of the codebase. * Use git-clang-format 16 to format your code. If clang-format-16 is not available on your Debian-based distribution, you can install it from https://apt.llvm.org/. @@ -69,23 +69,23 @@ git-clang-format-16 --extensions c,cpp,h,hpp,inc --style file dev ./sys/clang-format.py ``` -* Lines should be at most 100 chars. A tab is considered as 8 chars. If it makes +* Lines should be at most 100 characters. A tab is considered 8 characters. If it makes things more readable, you can use more than 100 characters, but this should be the exception, not the rule. * Always use braces for if and while. -* In general, don't use goto. The goto statement only comes in handy when a - function exits from multiple locations and some common work such as cleanup - has to be done. If there is no cleanup needed, then just return directly. -* Choose label names which say what the goto does or why the goto exists. An - example of a good name could be "out_buffer:" if the goto frees "buffer". +* In general, don't use goto. The `goto` statement is only useful when a + function has multiple exit points and needs to perform common cleanup + tasks. If there is no cleanup needed, then just return directly. +* Choose label names that describe what the `goto` does or why it exists. An + example of a good name could be `out_buffer:` if the `goto` frees `buffer`. Avoid using GW-BASIC names like "err1:" and "err2:". * Use `rz_return_*` functions to check preconditions that are caused by - programmers' errors. Please note the difference between conditions that should - never happen, and that are handled through `rz_return_*` functions, and - conditions that can happen at runtime (e.g. `malloc()` returns `NULL`, input coming - from user, etc.), and should be handled in the usual way through if-else. + programmers' errors. Note the difference between conditions that should + never happen (handled by `rz_return_*` functions) and conditions that + can occur at runtime (e.g., `malloc()` returning `NULL`, user input), which + should be handled with standard `if-else` blocks. ```c int check(RzCore *c, int a, int b) { @@ -100,8 +100,8 @@ int check(RzCore *c, int a, int b) { } ``` -* Use `rz_warn_if_reached()` macros to emit a runtime warning if the code path is reached. - It is often useful in a switch cases handling, in the default case: +* Use the `rz_warn_if_reached()` macro to emit a runtime warning if a code path is reached. + It is often useful in the `default` case of a `switch` statement: ```c switch(something) { @@ -118,7 +118,7 @@ switch(something) { } ``` -* Split long conditional expressions into small `static inline` functions to make them more readable: +* Split long conditional expressions into small `static inline` functions to improve readability: ```diff +static inline bool inRange(RzBreakpointItem *b, ut64 addr) { @@ -143,9 +143,9 @@ switch(something) { } ``` -* Structure in the C files +* Structure of C files -The structure of the C files in Rizin must be like this: +C files in Rizin must be structured as follows: ```c // SPDX-License-Identifier: LGPL-3.0-only @@ -157,9 +157,9 @@ RZ_IPI void internal(void) {} ## internal apis (used only inside the library) RZ_API void public(void) {} ## public apis starting with constructor/destructor ``` -* Why return int vs enum +* Why return `int` vs. `enum` -The reason why many places in Rizin-land functions return int instead of an enum type is because enums can't be OR'ed; otherwise, it breaks the usage within a switch statement and swig can't handle that stuff. +Many functions in Rizin return `int` instead of an `enum` type because enums cannot be OR'd, which would break their use in `switch` statements and cause issues with SWIG. ``` rz_core_wrap.cxx:28612:60: error: assigning to 'RzRegisterType' from incompatible type 'long' @@ -175,27 +175,27 @@ rz_core_wrap.cxx:32103:61: error: assigning to 'RzDebugReasonType' from incompat * You can use `export RZ_DEBUG_ASSERT=1` to set a breakpoint when hitting an assert. -* Function names should be explicit enough to not require a comment - explaining what it does when seen elsewhere in code. +* Function names should be descriptive enough that they don't require a + comment to explain their purpose. * Use `RZ_API` define to mark exportable (public) methods only for module APIs. -* The rest of functions must be static, to avoid polluting the global space. +* The rest of the functions must be `static`, to avoid polluting the global namespace. * Avoid using global variables, they are evil. -* Do not write ultra-large functions: split them into multiple or simplify - the algorithm, only external-copy-pasted-not-going-to-be-maintained code - can be accepted in this way. (gnu code, external disassemblers, etc..) +* Avoid writing extremely large functions. Instead, split them into smaller + functions or simplify the algorithm. The only exception is for externally + sourced code that will not be maintained (e.g., GNU code, external + disassemblers). -* Use the Rizin types instead of the ones in ``, which are known to cause some - portability issues. So, instead of `uint8_t`, use `ut8`, etc.. As a bonus point they - are shorter to write. +* Use Rizin types (e.g., `ut8`) instead of `` types (e.g., + `uint8_t`), as they are more portable and shorter to type. -* Never ever use `%lld` or `%llx`. This is not portable. Always use the `PFMT64x` - macros. Those are similar to the ones in GLIB. See all macroses in `librz/include/rz_types.h`. +* Never use `%lld` or `%llx`. They are not portable. Always use the `PFMT64x` + macros, which are similar to those in GLIB. See all macros in `librz/include/rz_types.h`. -* Never use `offsetof()` macros - it's not supported by some compilers. Use `rz_offsetof()` instead. +* Never use the `offsetof()` macro - it's not supported by all compilers. Use `rz_offsetof()` instead. * Add a single space after the `//` when writing inline comments: @@ -203,32 +203,32 @@ rz_core_wrap.cxx:32103:61: error: assigning to 'RzDebugReasonType' from incompat int sum = 0; // set sum to 0 ``` -* If you want to iterate over values of your struct, implement `RzIterator *mystruct_as_iter()` and `RzIterator *mystruct_as_iter_mut()` for them. +* If you want to iterate over the values of your struct, implement `RzIterator *mystruct_as_iter()` and `RzIterator *mystruct_as_iter_mut()` for it. See `rz_iterator.h` for details about the iterator. -* If you need bitmaps, do not shift and OR the bits manually on `ut32`. Use bit vectors from `rz_bitvector.h` instead. +* If you need bitmaps, do not manually shift and OR bits on a `ut32`. + Instead, use the bit vectors from `rz_bitvector.h`. ### Shell Scripts * Use `#!/bin/sh` -* Do not use bashisms `[[`, `$'...'` etc. +* Do not use bashisms such as `[[` and `$'...'`. -* Use our [shellcheck.sh](https://github.com/rizinorg/rizin/blob/master/sys/shellcheck.sh) script to check for problems and for bashisms. +* Use our [shellcheck.sh](https://github.com/rizinorg/rizin/blob/master/sys/shellcheck.sh) script to check for problems and bashisms. ### Python Scripts -* Code must run under Python 3.6 (for [Debian "wheezy" compatibility](https://github.com/rizinorg/rizin/pull/2870#issuecomment-1205338140)). +* Code must run under Python 3.6 for compatibility with Debian "wheezy". -# Manage Endianness +# Managing Endianness -As hackers, we need to be aware of endianness. +As developers, we need to be aware of endianness. -Endianness can become a problem when you try to process buffers or streams -of bytes and store intermediate values as integers with width larger than -a single byte. +Endianness can be a problem when processing byte streams and storing +intermediate values as integers wider than a single byte. -It can seem very easy to write the following code: +It may seem easy to write the following code: ```c ut8 opcode[4] = { 0x10, 0x20, 0x30, 0x40 }; ut32 value = *(ut32*)opcode; @@ -239,15 +239,16 @@ This needs to be avoided! Why? What is actually happening? -When you cast the opcode stream to a unsigned int, the compiler uses the endianness -of the host to interpret the bytes and stores it in host endianness. This leads to -very unportable code, because if you compile on a different endian machine, the -value stored in "value" might be 0x40302010 instead of 0x10203040. +When you cast the opcode stream to an unsigned int, the compiler uses the host's +endianness to interpret the bytes, storing the value in host-endian format. +This leads to non-portable code, because on a machine with different +endianness, the value stored in `value` might be `0x40302010` instead of +`0x10203040`. ## Solution -Use bitshifts and OR instructions to interpret bytes in a known endian. -Instead of casting streams of bytes to larger width integers, do the following: +Use bit-shifting and OR operations to interpret bytes in a known endianness. +Instead of casting byte streams to wider integer types, do the following: ```c ut8 opcode[4] = { 0x10, 0x20, 0x30, 0x40 }; ut32 value = opcode[0] | opcode[1] << 8 | opcode[2] << 16 | opcode[3] << 24; @@ -256,14 +257,14 @@ or if you prefer the other endian: ```c ut32 value = opcode[3] | opcode[2] << 8 | opcode[1] << 16 | opcode[0] << 24; ``` -This is much better because you actually know which endian your bytes are stored in -within the integer value, REGARDLESS of the host endian of the machine. +This is much better because you know the endianness of the bytes stored in +the integer value, regardless of the host machine's endianness. ## Endian helper functions -Rizin now uses helper functions to interpret all byte streams in a known endian. +Rizin uses helper functions to interpret all byte streams in a known endianness. -Please use these at all times, eg: +Please use these at all times, e.g.: ```c val32 = rz_read_be32(buffer) // reads 4 bytes from a stream in BE val32 = rz_read_le32(buffer) // reads 4 bytes from a stream in LE @@ -276,7 +277,7 @@ There are a number of helper functions for 64, 32, 16, and 8 bit reads and write (Note that 8 bit reads are equivalent to casting a single byte of the buffer to a `ut8` value, ie endian is irrelevant). -In case of the access to the `RzBuffer *buffer` type, there are also helpers like +For accessing `RzBuffer *buffer` types, there are also helpers like `rz_buf_read_bleXX()`/`rz_buf_write_bleXX()`, `rz_buf_read_bleXX_at()`/`rz_buf_write_bleXX_at()`, and `rz_buf_read_bleXX_offset()`/`rz_buf_write_bleXX_offset()`. In addition to them there are corresponding little-endian or big-endian-only functions @@ -285,10 +286,10 @@ like `rz_buf_read_leXX()`/`rz_buf_read_beXX()`, `rz_buf_read_leXX_at()`/`rz_buf_ ## Packed structures -Due to the various differences between platforms and compilers Rizin -has a special helper macro - `RZ_PACKED()`. Instead of non-portable -`#pragma pack` or `__attribute__((packed))` it is advised to use this macro -instead. To wrap the code inside of it you just need to write: +Due to differences between platforms and compilers, Rizin +has a special helper macro: `RZ_PACKED()`. Instead of the non-portable +`#pragma pack` or `__attribute__((packed))`, it is advisable to use this macro +instead. To use it, wrap your code as follows: ```c RZ_PACKED(union mystruct { int a; @@ -305,9 +306,9 @@ RZ_PACKED(typedef structmystruct { ## Modules -The Rizin code base is modularized into different libraries that are -found in `librz/` directory. The `binrz/` directory contains the programs -which use the libraries. +The Rizin codebase is modularized into different libraries located in the +`librz/` directory. The `binrz/` directory contains the programs that use +these libraries. Hint: To find both the declaration and definition of a function named *func_name*, you can use the following `git grep` command: @@ -318,11 +319,12 @@ git grep -nWG "^[^[:blank:]].*func_name(" ## JSON -Since many places in Rizin output JSON the special API was created, **PJ** which means "Print Json". -It allows to create nested JSON structs with a simple and short API. Full API reference is -available in `librz/include/rz_util/rz_pj.h`. +Since many parts of Rizin output JSON, a special API called **PJ** (Print +JSON) was created. It provides a simple and concise API for creating nested +JSON structures. The full API reference is available in +`librz/include/rz_util/rz_pj.h`. -Here is the short example of how we usually use **PJ**: +Here is a short example of how **PJ** is typically used: ```c PJ *pj = NULL; if (mode == RZ_OUTPUT_MODE_JSON) { @@ -334,10 +336,10 @@ if (mode == RZ_OUTPUT_MODE_JSON) { // ... some other logic // Creating the JSON structure if (mode == RZ_OUTPUT_MODE_JSON) { - pj_o(pj); // creates a JSON list + pj_o(pj); // creates a JSON object pj_ki(pj, "id", some->id); // creates an element like "id": 6 pj_ks(pj, "name", some->name); // creates an element like "name": "bla" - pj_end(pj); // closes a JSON list + pj_end(pj); // closes a JSON object } // ... some other logic // Printing the JSON on the screen @@ -353,12 +355,12 @@ It will produce the following output: ## Licenses -Rizin is trying to comply with the Software Package Data Exchange® (SPDX®), -an open standard to communicate in a clear way licenses and copyrights, among -other things, of a software. All files in the repository should either have -an header specifying the copyright and the license that apply or an entry in -.reuse/dep5 file. All pieces of code copied from other projects should have -a license/copyright entry as well. +Rizin strives to comply with the Software Package Data Exchange® (SPDX®), +an open standard for communicating software licensing, copyright, and other +information. All files in the repository should either have a header +specifying the applicable copyright and license, or an entry in the +`.reuse/dep5` file. All code copied from other projects should also have a +license/copyright entry. In particular, the SPDX header may look like: ```C @@ -366,12 +368,13 @@ In particular, the SPDX header may look like: // SPDX-License-Identifier: LPGL-3.0-only ``` -You can use the [REUSE Software](https://reuse.software/) to check the -compliance of the project and get the licenses/copyright of each file. +You can use [REUSE Software](https://reuse.software/) to check the project's +compliance and retrieve the license and copyright information for each file. # Custom Pointer Modifiers -In Rizin code, there are some conventions to help developers use pointers more safely, which are defined in `librz/include/rz_types.h`: +The Rizin codebase has conventions to help developers use pointers more +safely, which are defined in `librz/include/rz_types.h`: ```c #define RZ_IN /* do not use, implicit */ @@ -386,30 +389,33 @@ In Rizin code, there are some conventions to help developers use pointers more s ### Usage of Modifiers -Most of these modifiers are self-explanatory, and you can see brief explanations in the comments. However, `RZ_OWN` and `RZ_BORROW` can be a bit tricky for new developers. +Most of these modifiers are self-explanatory, with brief explanations in the +comments. However, `RZ_OWN` and `RZ_BORROW` can be tricky for new +developers. -Sometimes it may not be immediately clear whether the object you are getting from a function shall be freed or not. -Rizin uses `RZ_OWN` and `RZ_BORROW` to indicate pointer ownership, -so you don't have to read complicated function definitions to know whether they should still free objects or not. +Sometimes it may not be immediately clear whether an object returned from a +function should be freed. Rizin uses `RZ_OWN` and `RZ_BORROW` to indicate +pointer ownership, so you don't have to read complex function definitions to +determine if you need to free an object. You can use the two modifiers in two places, and their explanations are as follows: - **Before the return type of a function**: - - `RZ_OWN`: The ownership of the returned object is transferred to the caller. The caller *owns* the object, so it must free it (or ensure that something else frees it). - - `RZ_BORROW`: The ownership of the returned object is not transferred. The caller can use the object, but it does not own it, so it should not free it. + - `RZ_OWN`: The ownership of the returned object is transferred to the caller. The caller *owns* the object and must free it (or ensure that it is freed elsewhere). + - `RZ_BORROW`: The ownership of the returned object is not transferred. The caller can use the object but does not own it, so it must not free it. - **Before the parameter of a function**: - - `RZ_OWN`: The ownership of the passed argument is transferred to the callee. The callee now owns the object and it is its duty to free it (or ensure that something else frees it). In any case, the caller should not care anymore about freeing that passed object. - - `RZ_BORROW`: The ownership of the passed argument is *not* transferred to the callee, which can use it but it should not free it. After calling this function, the caller still owns the passed object and it should ensure that at some point it is freed. + - `RZ_OWN`: The ownership of the passed argument is transferred to the callee. The callee now owns the object and is responsible for freeing it (or ensuring it is freed elsewhere). In any case, the caller should no longer be concerned with freeing the passed object. + - `RZ_BORROW`: The ownership of the passed argument is *not* transferred to the callee, which can use it but must not free it. After calling this function, the caller still owns the passed object and must ensure it is eventually freed. ### Guidelines for Functions #### Functions Returning Pointers - **Arguments (Pointers)**: Must have both ownership and nullability definitions specified. -- **Return Value**: Must have ownership defined and, unless otherwise specified, it is assumed to be `RZ_NULLABLE`. +- **Return Value**: Must have ownership defined and is assumed to be `RZ_NULLABLE` unless otherwise specified. #### Functions Handling `NULL` Pointers - **Arguments (Pointers)**: Must be marked with `RZ_NULLABLE`. -- **Assertions**: There should not be any assertions on these arguments as the function is expected to handle `NULL` pointers. +- **Assertions**: There should be no assertions on these arguments, as the function is expected to handle `NULL` pointers. ### Examples: @@ -424,10 +430,10 @@ RZ_OWN MyString *capitalize_str(RZ_BORROW char *s) { int main() { char *s = rz_str_dup("Hello World"); MyString *m = capitalize_str(s); - // s was RZ_BORROW, so main MUST free it + // `s` was RZ_BORROW, so `main` MUST free it free(s); // ... use m .... - // m was RZ_OWN, so main now has to free it + // `m` was RZ_OWN, so `main` now has to free it my_string_free(m); } ``` @@ -445,14 +451,18 @@ int main() { char *s = strdup("Hello World"); MyFile *f = create_my_file(); MyString *m = capitalize_str(f, s); - // s was RZ_OWN, so main does not need to free it. s is now owned by `m` + // `s` was RZ_OWN, so `main` does not need to free it. `s` is now owned by `m` // ... use m .... - // m was RZ_BORROW, so main is just borrowing it from `f`, and it does not have to free it. + // `m` was RZ_BORROW, so `main` is just borrowing it from `f`, and it does not have to free it. my_file_free(f); - // f was created by main and never transferred to anything else, so main needs to free it. + // `f` was created by `main` and its ownership was never transferred, so `main` needs to free it. } ``` - You should use these modifiers consistently in both function definition and declaration. -- You should use these modifiers when and only when it makes sense. For example, if your function returns `const char *`, the caller should not free it because of the `const`. So specifying `RZ_BORROW` in this case is probably redundant. -- Since they are used as indications to developers with no special compiler-time restrictions, there is no good way to check if you have used them correctly. +- You should use these modifiers only when it makes sense. For example, if a + function returns a `const char *`, the caller should not free it because it + is `const`. Therefore, specifying `RZ_BORROW` in this case is probably + redundant. +- Since they are hints to developers with no special compiler-time + enforcement, there is no easy way to verify their correct usage. diff --git a/README.md b/README.md index 70189eb9edb..373ef312ccc 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,24 @@ # Rizin -Rizin is a reverse engineering framework, born as a fork of the radare2, with -a focus on usability, features and cleanliness. +Rizin is a reverse engineering framework, born as a fork of radare2, with +a focus on usability, features, and cleanliness. Rizin is portable and it can be used to analyze binaries, disassemble code, debug programs, as a forensic tool, as a scriptable command-line hexadecimal editor able to open disk files, and much more! -To learn more on Rizin you may want to read the +To learn more about Rizin you may want to read the [official Rizin book](https://book.rizin.re). # How to install -Look at [install instructions](https://rizin.re/install/) on our web page. +See the [install instructions](https://rizin.re/install/) on our web page. # How to build -Use `meson` to compile and install Rizin. Please make sure to get an updated -`meson` (e.g. get it with `pip install meson` if your system does not provide +Use `meson` to compile and install Rizin. Please make sure you have an updated +version of `meson` (e.g. get it with `pip install meson` if your system does not provide one that is at least version `0.55.0`). Clone this repository: @@ -50,8 +50,8 @@ Please have a look at [BUILDING.md][] for more information about building Rizin. # Contributing We very much welcome any kind of contributions, from typos, to documentation, to -refactoring, up to completely new features you may think of. Before -contributing, we would like you to read the file [CONTRIBUTING.md][], so that we +refactoring, up to completely new features. Before +contributing, we would like you to read [CONTRIBUTING.md][], so that we can all be on the same page. ## Tests @@ -92,21 +92,21 @@ Game Boy (Advance), Nintendo DS ROMs and Nintendo 3DS FIRMs. Apart from the main tool `rizin`, there are also other tools tailored for specific purposes and useful for shell scripting or as separate standalone tools: -- `rz-bin` - provides all kind of information about binary formats -- `rz-asm` - a command-line assembler and disassemblers -- `rz-diff` - a tool to compare two binaries as raw data or analyzed executables -- `rz-hash` - allows to calculate different hashes or even encrypt data -- `rz-gg` - a small "eggs" code generator useful for exploitation purposes -- `rz-find` - binary analog of `find` tool, allowing to search patterns and bit masks -- `rz-sign` - tool to create, convert and parse FLIRT signatures +- `rz-bin` - provides all kinds of information about binary formats +- `rz-asm` - a command-line assembler and disassembler +- `rz-diff` - a tool for comparing two binaries as raw data or analyzed executables +- `rz-hash` - allows calculating different hashes or even encrypting data +- `rz-gg` - a small "egg" code generator useful for exploitation purposes +- `rz-find` - binary analog of the `find` tool, allowing searches for patterns and bitmasks +- `rz-sign` - a tool to create, convert, and parse FLIRT signatures - `rz-ax` - a calculator and number format converter -- `rz-run` - a tool that allows to specify running environment and arguments for debugged file +- `rz-run` - a tool that allows specifying the running environment and arguments for a debugged file ## Scripting We provide a way to interact with Rizin from Python, Haskell, OCaml, Ruby, Rust, and Go languages through [rzpipe](https://github.com/rizinorg/rz-pipe). -Other languages although not currently supported could be easily added. +Other languages, although not currently supported, could be easily added. # Community diff --git a/binrz/man/rizin.1 b/binrz/man/rizin.1 index ebad450acbc..9fcbe1a9f34 100644 --- a/binrz/man/rizin.1 +++ b/binrz/man/rizin.1 @@ -2,7 +2,7 @@ .Dt RIZIN 1 .Sh NAME .Nm rizin -.Nd Advanced commandline hexadecimal editor, disassembler and debugger +.Nd Advanced command-line hexadecimal editor, disassembler, and debugger .Sh SYNOPSIS .Nm rizin .Op Fl ACdfLMnNqStuvwzX @@ -18,152 +18,152 @@ .Op Fl e Ar k=v .Ar file|pid|-|--|= .Sh DESCRIPTION -Rizin is a command-line reverse engineering framework designed to analyze and +Rizin is a command-line reverse-engineering framework designed to analyze and disassemble binary files. It provides various tools and features for analyzing and understanding the structure, behavior, and logic of executable files. .Pp The options are: .Bl -tag -width Fl .It Ar -- -Run rizin without opening any file +Run Rizin without opening any file. .It Ar = -Equivalent of 'rizin malloc://512' +Equivalent of 'rizin malloc://512'. .It Ar - -Read file from stdin +Read file from standard input. .It Ar -= -Perform R=! command to run all commands remotely +Perform `R=!` command to run all commands remotely. .It Fl 0 -Print \\x00 after initialization and after every command executed +Print `\\x00` after initialization and after every command executed. .It Fl 1 -Redirect stderr to stdout +Redirect stderr to stdout. .It Fl 2 -Close stderr file descriptor (silent warning messages) +Close the `stderr` file descriptor (silent warning messages). .It Fl a Ar arch -Set the assembly architecture.(x86, ppc, arm, mips, bf, java, ...) +Set the assembly architecture (e.g., `x86`, `ppc`, `arm`, `mips`, `bf`, `java`, etc.). .It Fl A -Run 'aaa' command before prompt or patch to analyze all referenced code +Run the `aaa` command before the prompt or patch to analyze all referenced code. .It Fl b Ar bits -Set the assembly bitness. (16, 32, 64) +Set the assembly bitness (16, 32, or 64). .It Fl B Ar baddr -Set the base address for Position-Independent Executables (PIE) +Set the base address for Position-Independent Executables (PIE). .It Fl c Ar 'cmd..' -Execute the specified Rizin command +Execute the specified Rizin command. .It -C -Specify a file in the format "host:port" to run Rizin remotely through HTTP +Specify a file in the format `host:port` to run Rizin remotely through HTTP. .It Fl d -Debug the executable 'file' or running process 'pid' +Debug the executable `file` or running process `pid`. .It Fl D Ar backend -Enable debug mode, setting the configuration variable 'cfg.debug=true' +Enable debug mode, setting the configuration variable `cfg.debug=true`. .It Fl e Ar k=v -Evaluate the specified configuration variable +Evaluate the specified configuration variable. .It Fl f -Set block size to be equal to file size +Set the block size to be equal to the file size. .It -F binplugin -Force the use of a specific rbin plugin +Force the use of a specific `rbin` plugin. .It Fl h, hh -Show help messages, with -hh showing detailed help +Show help messages, with `-hh` showing detailed help. .It Fl H Ar [var] -Print information about the installation paths and configuration settings of Rizin. This option is useful for obtaining details about the installation location, directories, and various components of Rizin +Print information about the installation paths and configuration settings of Rizin. This option is useful for obtaining details about the installation location, directories, and various components of Rizin. .It Fl i Ar file -Run the commands from the script file +Run the commands from the script file. .It Fl I Ar file -Run script file. Before the file is loaded +Run the script file before the file is loaded. .It Fl k Ar OS/kern -Set the assembly operating system +Set the assembly operating system. .It Fl l Ar lib -Load the specified plugin file +Load the specified plugin file. .It Fl L -List supported IO plugins +List supported IO plugins. .It Fl m Ar addr -Map file at given address +Map the file at the given address. .It Fl M -Disable demangling +Disable demangling. .It Fl n, nn -Control loading of RzBin info, with -nn only loading binary structures +Control the loading of RzBin info, with `-nn` only loading binary structures. .It Fl N -Disable user settings/projects from ~/.rizinrc, ~/.config/rizin/rizinrc and the scripts inside .../rizinrc.d/ directory +Disable user settings/projects from `~/.rizinrc`, `~/.config/rizin/rizinrc`, and the scripts inside the `.../rizinrc.d/` directory. .It Fl NN -Disable loading any scripts or plugins +Disable loading any scripts or plugins. .It Fl q -Quiet mode, suppresses prompt and quits after script execution +Quiet mode; suppresses the prompt and quits after script execution. .It Fl qq -Quit before showing the prompt. Right after all the -e -c and -i arguments are evaluated +Quit before showing the prompt, right after all the `-e`, `-c`, and `-i` arguments are evaluated. .It Fl Q -Same as q, but exiting without freeing RzCore, this produces leaks at exit time, but saves some precious ms to run the testsuite in fast mode +Same as `q`, but exits without freeing RzCore. This produces leaks at exit time but saves some precious milliseconds to run the test suite in fast mode. .It Fl p Ar prj -Set project file +Set the project file. .It Fl r Ar rz-run -Specify dbg.profile rz-run profile to use when spawning a program for debugging +Specify the `dbg.profile` `rz-run` profile to use when spawning a program for debugging. .It Fl R Ar rule -Specify custom rz-run directives without having to create a rz-run profile +Specify custom `rz-run` directives without having to create an `rz-run` profile. .It Fl s Ar addr -Start seeking at this address +Start seeking at this address. .It Fl T -Avoid computing the file hashes +Avoid computing the file hashes. .It Fl u -Set bin.filter=false to load rbin info without filtering names +Set `bin.filter=false` to load `rbin` info without filtering names. .It Fl v -Show version information and exit (Use -qv to get just the version number) +Show version information and exit. (Use `-qv` to get just the version number). .It Fl V -Show rizin library versions +Show Rizin library versions. .It Fl w -Open in write mode +Open in write mode. .It Fl x -Open the file without the execute flag +Open the file without the execute flag. .It Fl X -Same as -e bin.usextr=false, do not use extract plugins, useful for dyldcache +Same as `-e bin.usextr=false`; do not use extract plugins. Useful for `dyldcache`. .It Fl z, zz -do not load strings or load them even in raw +Do not load strings, or load them even in raw. .El .Sh ENVIRONMENT .Pp -ANSICON: ansicon's W & H of the buffer and w & h of the window in the form of: "WxH (wxh)" +ANSICON: Ansicon's W & H of the buffer and w & h of the window in the form of: `WxH (wxh)`. .Pp -DEBUGINFOD_URLS: e bin.dbginfo.debuginfod_urls - use alternative debuginfod server +DEBUGINFOD_URLS: `e bin.dbginfo.debuginfod_urls` - Use an alternative `debuginfod` server. .Pp -COLUMNS: terminal columns to use +COLUMNS: Terminal columns to use. .Pp -RZ_ABORTLEVEL: target log level/severity when to abort (0:DEBUG, 1:VERBOSE, 2:INFO, 3:WARN, 4:ERROR, 5:FATAL) +RZ_ABORTLEVEL: Target log level/severity at which to abort (0:DEBUG, 1:VERBOSE, 2:INFO, 3:WARN, 4:ERROR, 5:FATAL). .Pp -RZ_CURL: whether to use curl (for SSL support) +RZ_CURL: Whether to use `curl` (for SSL support). .Pp -RZ_DEBUG_ASSERT: set a breakpoint when hitting an assert +RZ_DEBUG_ASSERT: Set a breakpoint when hitting an assert. .Pp -RZ_DEBUG_TOOL debug tool to use when showing error messages and crash signal +RZ_DEBUG_TOOL Debug tool to use when showing error messages and crash signals. .Pp -RZ_DYLDCACHE_FILTER: dyld cache filter (MacOS dynamic libraries location(s) at runtime) +RZ_DYLDCACHE_FILTER: Dyld cache filter (macOS dynamic libraries location(s) at runtime). .Pp -RZ_HTTP_AUTHFILE: HTTP Authentification user file +RZ_HTTP_AUTHFILE: HTTP authentication user file. .Pp -RZ_LOGCOLORS: should the log output use colors (TODO) +RZ_LOGCOLORS: Should the log output use colors (TODO). .Pp -RZ_LOGFILE: logging output filename/path +RZ_LOGFILE: Logging output filename/path. .Pp -RZ_LOGLEVEL: target log level/severity (0:DEBUG, 1:VERBOSE, 2:INFO, 3:WARN, 4:ERROR, 5:FATAL) +RZ_LOGLEVEL: Target log level/severity (0:DEBUG, 1:VERBOSE, 2:INFO, 3:WARN, 4:ERROR, 5:FATAL). .Pp -RZ_LOGSHOWSOURCES: should the log output contain src info (filename:lineno) +RZ_LOGSHOWSOURCES: Should the log output contain source info (`filename:lineno`). .Pp -RZ_PIPE_IN: rzpipe cmd input (file descriptor) +RZ_PIPE_IN: `rzpipe` command input (file descriptor). .Pp -RZ_PIPE_OUT: rzpipe cmd output (file descriptor) +RZ_PIPE_OUT: `rzpipe` command output (file descriptor). .Pp -RZ_PREFIX: default prefix rizin was compiled for +RZ_PREFIX: Default prefix Rizin was compiled for. .Pp -RZ_RCFILE: user config file +RZ_RCFILE: User config file. .Pp -SFLIBPATH: SFLib syscall library path +SFLIBPATH: `SFLib` syscall library path. .Sh EXAMPLE .Pp -Start rizin in analysis mode (-A) on the /bin/ls executable: +Start Rizin in analysis mode (`-A`) on the `/bin/ls` executable: .Pp .Nm rizin Fl A Ar /bin/ls .Pp -Open the file /bin/ls in write mode, allowing you to make changes to the binary: +Open the file `/bin/ls` in write mode, allowing you to make changes to the binary: .Pp .Nm rizin Fl w Ar /bin/ls .Pp -Start rizin's debugger (-d) on /bin/ls and passes arguments "-l" and "/tmp" to the program for debugging: +Start Rizin's debugger (`-d`) on `/bin/ls` and pass the arguments `-l` and `/tmp` to the program for debugging: .Pp .Nm rizin Fl d Ar /bin/ls Fl l Ar /tmp .Pp diff --git a/binrz/man/rz-asm.1 b/binrz/man/rz-asm.1 index ae43095cf40..b6d9887b515 100644 --- a/binrz/man/rz-asm.1 +++ b/binrz/man/rz-asm.1 @@ -2,7 +2,7 @@ .Dt RZ_ASM 1 .Sh NAME .Nm rz-asm -.Nd rizin assembler and disassembler tool +.Nd Rizin assembler and disassembler tool .Sh SYNOPSIS .Nm rz-asm .Op Fl ABCdDeIEhjLpqrvxw @@ -22,146 +22,146 @@ .Sh DESCRIPTION This command is part of the Rizin project. .Pp -This tool uses RzAsm to assemble and disassemble files or hexpair strings. It supports a large list of architectures which can be listed using the \-L flag. +This tool uses RzAsm to assemble and disassemble files or hex-pair strings. It supports a large list of architectures, which can be listed using the `-L` flag. .Pp .Bl -tag -width Fl .It Fl a Ar arch -Set architecture to assemble/disassemble (see -L) +Set the architecture to assemble/disassemble (see `-L`). .It Fl A -Show analysis information from given hexpairs +Show analysis information from the given hex-pairs. .It Fl b Ar bits -Set CPU register size (8, 16, 32, 64) (RZ_ASM_BITS) +Set the CPU register size (8, 16, 32, or 64) (RZ_ASM_BITS). .It Fl B -Binary input/output (-l is mandatory for binary input) +Binary input/output (`-l` is mandatory for binary input). .It Fl c Ar CPU -Select specific CPU (depends on the arch) +Select a specific CPU (depends on the architecture). .It Fl C -Output in C format +Output in C format. .It Fl d, D -Disassemble from hexpair bytes (-D show hexpairs) +Disassemble from hex-pair bytes (`-D` shows hex-pairs). .It Fl e -Use big endian instead of little endian +Use big-endian instead of little-endian. .It Fl I -Display lifted RzIL code (same input as in -d, IL is also validated) +Display lifted RzIL code (same input as in `-d`; IL is also validated). .It Fl E -Display ESIL expression (same input as in -d) +Display the ESIL expression (same input as in `-d`). .It Fl f Ar file -Read data from file +Read data from a file. .It Fl F Ar in:out -Specify input and/or output filters (att2intel, x86.pseudo, ...) +Specify input and/or output filters (`att2intel`, `x86.pseudo`, etc.). .It Fl h, hh -Show usage help message, hh for long +Show the usage help message; `hh` for long. .It Fl i Ar len -Ignore N bytes of the input buffer +Ignore N bytes of the input buffer. .It Fl j -Output in JSON format +Output in JSON format. .It Fl k Ar kernel -Select operating system (linux, windows, darwin, ..) +Select the operating system (`linux`, `windows`, `darwin`, etc.). .It Fl l Ar len -Input/Output length +Input/output length. .It Fl L -List asm plugins: (a=asm, d=disasm, A=analyze, e=ESIL, I=RzIL) +List `asm` plugins (`a`=asm, `d`=disasm, `A`=analyze, `e`=ESIL, `I`=RzIL). .It Fl m Ar plugin -List supported CPUs for the chosen plugin +List the supported CPUs for the chosen plugin. .It Fl o, @ Ar addr -Set start address for code (default 0) +Set the start address for the code (default 0). .It Fl O Ar file -Output file name (rz-asm -Bf a.asm -O a) +Output file name (`rz-asm -Bf a.asm -O a`). .It Fl p -Run SPP over input for assembly +Run SPP over the input for assembly. .It Fl q -Quiet mode +Quiet mode. .It Fl r -Output in rizin commands +Output in Rizin commands. .It Fl s Ar syntax -Select syntax (intel, att) +Select the syntax (`intel`, `att`). .It Fl v -Show version information +Show version information. .It Fl x -Use hex dwords instead of hex pairs when assembling +Use hex dwords instead of hex-pairs when assembling. .It Fl w -Describe opcode +Describe the opcode. .El .Sh Directives .Pp .Bl -tag -width .It Ic .intel_syntax -Use Intel syntax rather than AT&T +Use Intel syntax rather than AT&T. .It Ic .att_syntax -Use AT&T syntax rather than Intel +Use AT&T syntax rather than Intel. .It Ic .align Ar number -Set the code or data alignment +Set the code or data alignment. .It Ic .arch Ar name -Set the code architecture +Set the code architecture. .It Ic .arm -Set the ARM mode (as opposed to Thumb) for ARM architecture +Set the ARM mode (as opposed to Thumb) for the ARM architecture. .It Ic .ascii Ar string -Define the ASCII string +Define an ASCII string. .It Ic .asciz Ar string -Define the zero-ending ASCII string +Define a zero-ending ASCII string. .It Ic .bits Ar number -Define the code bitness +Define the code bitness. .It Ic .big_endian -Set the BE (big endian) byte order +Set the BE (big-endian) byte order. .It Ic .cpu Ar name -Set the CPU for the chosen architecture +Set the CPU for the chosen architecture. .It Ic .data -Mark the start of the data section +Mark the start of the data section. .It Ic .endian Ar 1|0 -Set the endianness (the byte order) - 1 is BE, 0 is LE +Set the endianness (the byte order) - 1 is BE, 0 is LE. .It Ic .equ Ar name Ar value -Define the constant +Define a constant. .It Ic .fill Ar repeat,size,value -Fill the data with the repeating value pattern +Fill the data with the repeating value pattern. .It Ic .hex Ar data -Define the data in hexadecimal format +Define the data in hexadecimal format. .It Ic .incbin Ar filename -Include binary file +Include a binary file. .It Ic .int16 Ar number -Define 16-bit integer +Define a 16-bit integer. .It Ic .int32 Ar number -Define 32-bit integer +Define a 32-bit integer. .It Ic .int64 Ar number -Define 64-bit integer +Define a 64-bit integer. .It Ic .kernel Ar name -Set the kernel for syscalls +Set the kernel for syscalls. .It Ic .little_endian -Set the LE (little endian) byte order +Set the LE (little-endian) byte order. .It Ic .org Ar value -Set the value of the PC (Program Counter) register +Set the value of the PC (Program Counter) register. .It Ic .os Ar name -Set the operating system for syscalls +Set the operating system for syscalls. .It Ic .short Ar number -Define 16-bit integer +Define a 16-bit integer. .It Ic .string Ar string -Define the ASCII string +Define an ASCII string. .It Ic .text -Mark the start of the text section +Mark the start of the text section. .It Ic .thumb -Set the Thumb mode (as opposed to ARM) for ARM architecture +Set the Thumb mode (as opposed to ARM) for the ARM architecture. .El .Sh ENVIRONMENT .Pp -RZ_ARCH: e asm.arch - architecture to assemble/disassemble (same as rz-asm -a) +`RZ_ARCH`: `e asm.arch` - Architecture to assemble/disassemble (same as `rz-asm -a`). .Pp -RZ_ASM_ARCH: architecture to assemble/disassemble (same as rz-asm -a) +`RZ_ASM_ARCH`: Architecture to assemble/disassemble (same as `rz-asm -a`). .Pp -RZ_ASM_BITS: cpu register size (8, 16, 32, 64) (same as rz-asm -b) +`RZ_ASM_BITS`: CPU register size (8, 16, 32, or 64) (same as `rz-asm -b`). .Pp -RZ_BITS: e asm.bits - cpu register size (8, 16, 32, 64) (same as rz-asm -b) +`RZ_BITS`: `e asm.bits` - CPU register size (8, 16, 32, or 64) (same as `rz-asm -b`). .Pp -RZ_DEBUG: if defined, show error messages and crash signal\n" +`RZ_DEBUG`: If defined, show error messages and crash signals. .Pp -RZ_NOPLUGINS: do not load shared plugins (speedup loading)\n" +`RZ_NOPLUGINS`: Do not load shared plugins (speeds up loading). .Sh EXAMPLES .Pp -Assemble opcode: +Assemble an opcode: .Pp .Nm rz-asm Fl a Cm x86 Fl b Cm 32 Ar 'mov eax, 33' .Pp -Disassemble opcode: +Disassemble an opcode: .Pp .Nm rz-asm Fl d Cm 90 .Sh SEE ALSO diff --git a/binrz/man/rz-ax.1 b/binrz/man/rz-ax.1 index 60f71ce6934..d0c128ac6e1 100644 --- a/binrz/man/rz-ax.1 +++ b/binrz/man/rz-ax.1 @@ -2,7 +2,7 @@ .Dt RZ_AX 1 .Sh NAME .Nm rz-ax -.Nd rizin base converter +.Nd Rizin base converter .Sh SYNOPSIS .Nm rz-ax .Op Fl ebBdDeEfFhiIklLosStuvwx @@ -10,73 +10,73 @@ .Sh DESCRIPTION This command is part of the Rizin project. .Pp -This command allows you to convert values between positive and negative integer, float, octal, binary, ternary, and hexadecimal values. +This command allows you to convert values between positive and negative integers, floats, and octal, binary, ternary, and hexadecimal values. .Sh OPTIONS .Bl -tag -width Fl .It Fl a -Show ASCII table +Show the ASCII table. .It Fl b -Convert from binary to string (rz-ax -b 01000101 01110110) +Convert from binary to a string (`rz-ax -b 01000101 01110110`). .It Fl B -Convert from string to binary (rz-ax -B hello) +Convert from a string to binary (`rz-ax -B hello`). .It Fl d -Force output as integer (rz-ax -d 3 outputs 3 instead of 0x3) +Force output as an integer (`rz-ax -d 3` outputs `3` instead of `0x3`). .It Fl D -Base64 decode +Base64-decode. .It Fl e -Swap endianness (rz-ax -e 0x33) +Swap endianness (`rz-ax -e 0x33`). .It Fl E -Base64 encode +Base64-encode. .It Fl f -Floating point arithmetic (rz-ax -f 6.3+2.1) +Floating-point arithmetic (`rz-ax -f 6.3+2.1`). .It Fl F -Read C strings from stdin and output in hexpairs. Useful to load shellcodes (rz-ax -F < shellcode.[c/py/js]) +Read C strings from `stdin` and output in hex-pairs. Useful for loading shellcodes (`rz-ax -F < shellcode.[c/py/js]`). .It Fl h -Show usage help message +Show the usage help message. .It Fl i -Dump stdin to C array in stdout (rz-ax -i < bytes) +Dump `stdin` to a C array in `stdout` (`rz-ax -i < bytes`). .It Fl I -Convert LONG to/from IP ADDRESS (rz-ax -I 3530468537) +Convert a LONG to/from an IP ADDRESS (`rz-ax -I 3530468537`). .It Fl k -Keep the same base as the input data (rz-ax -k 33+3 -> 36) +Keep the same base as the input data (`rz-ax -k 33+3 -> 36`). .It Fl l -Append newline to the decoded output +Append a newline to the decoded output. .It Fl L -Convert binary to hexadecimal (rz-ax -L 111111111 outputs 0x1ff) +Convert binary to hexadecimal (`rz-ax -L 111111111` outputs `0x1ff`). .It Fl n -Show hexpairs from integer value (rz-ax -n 0x1234 # 34120000) +Show hex-pairs from an integer value (`rz-ax -n 0x1234 # 34120000`). .It Fl N -Show hex C string from integer value (rz-ax -N 0x1234 # \x34\x12\x00\x00) +Show a hex C string from an integer value (`rz-ax -N 0x1234 # \\x34\\x12\\x00\\x00`). .It Fl o -Convert from octal string to char (rz-ax -o \162 \172 # rz) +Convert from an octal string to a character (`rz-ax -o \\162 \\172 # rz`). .It Fl r -Rz style output (rz-ax -r 0x1234) +Rizin-style output (`rz-ax -r 0x1234`). .It Fl s -Convert from hex string to character (rz-ax -s 43 4a 50) +Convert from a hex string to a character (`rz-ax -s 43 4a 50`). .It Fl S -Convert from character to hex string (rz-ax -S < /bin/ls > ls.hex) +Convert from a character to a hex string (`rz-ax -S < /bin/ls > ls.hex`). .It Fl t -Convert Unix timestamp to string (rz-ax -t 1234567890) +Convert a Unix timestamp to a string (`rz-ax -t 1234567890`). .It Fl m -Convert MS-DOS timestamp to string (rz-ax -m 0x12345678) +Convert an MS-DOS timestamp to a string (`rz-ax -m 0x12345678`). .It Fl W -Convert Win32 timestamp to string (rz-ax -W 1234567890) +Convert a Win32 timestamp to a string (`rz-ax -W 1234567890`). .It Fl u -Convert given value to human readable units format (rz-ax -u 389289238 # 317.0M) +Convert a given value to a human-readable units format (`rz-ax -u 389289238 # 317.0M`). .It Fl v -Show version information +Show version information. .It Fl w -Convert signed word (rz-ax -w 16 0xffff) +Convert a signed word (`rz-ax -w 16 0xffff`). .It Fl x -Convert a string into a hash (rz-ax -x linux osx) +Convert a string into a hash (`rz-ax -x linux osx`). .It Fl p -Show position of set bits in the binary representation (rz-ax -p 0xb3) +Show the position of set bits in the binary representation (`rz-ax -p 0xb3`). .El .Sh USAGE .Pp Force output mode (numeric base) .Pp - =f floating point + =f floating-point =2 binary =3 ternary =8 octal @@ -104,7 +104,7 @@ Available variable types are: raw \-> hex rz-ax -S < /binfile hex \-> raw rz-ax -s 414141 .Pp -With no arguments, rz-ax read values from stdin. You can pass one or more values +With no arguments, `rz-ax` reads values from `stdin`. You can pass one or more values as arguments. .Pp $ rz-ax 33 0x41 0101b @@ -112,7 +112,7 @@ as arguments. 65 0x5 .Pp -You can do 'unpack' hexpair encoded strings easily. +You can 'unpack' hex-pair encoded strings easily. .Pp $ rz-ax \-s 41 42 43 ABC @@ -123,7 +123,7 @@ And it supports some math operations. 0x5*101b+5 30 .Pp -It is a very useful tool for scripting, so you can read floating point values, or get the integer offset of a jump or a stack delta when analyzing programs. +It is a very useful tool for scripting, so you can read floating-point values, or get the integer offset of a jump or a stack delta when analyzing programs. .Pp .Sh SEE ALSO .Pp diff --git a/binrz/man/rz-bin.1 b/binrz/man/rz-bin.1 index d17cb58c282..40443435f01 100644 --- a/binrz/man/rz-bin.1 +++ b/binrz/man/rz-bin.1 @@ -2,7 +2,7 @@ .Dt RZ_BIN 1 .Sh NAME .Nm rz-bin -.Nd Binary program info extractor +.Nd Binary program information extractor .Sh SYNOPSIS .Nm rz-bin .Op Fl AcdeEghHiIjlLMqrRsSUvVxzZ @@ -24,171 +24,171 @@ .Sh DESCRIPTION This command is part of the Rizin project. .Pp -rz-bin can analyze and extract useful information from binary executable files like ELF, PE, Mach-O, etc. It supports multiple architectures like x86, ARM, MIPS, PowerPC, etc. +`rz-bin` can analyze and extract useful information from binary executable files like ELF, PE, Mach-O, etc. It supports multiple architectures like x86, ARM, MIPS, PowerPC, etc. .Sh OPTIONS .Bl -tag -width Fl .It Fl @ Ar addr -Show section, symbol, or import at the given address +Show a section, symbol, or import at the given address. .It Fl A -List sub-binaries and their arch-bits pairs +List sub-binaries and their arch-bits pairs. .It Fl a Ar arch -Set architecture (x86, arm, .. or _) +Set the architecture (`x86`, `arm`, etc., or `_`). .It Fl b Ar bits -Set bits (32, 64 ...) +Set the bits (32, 64, etc.). .It Fl B Ar addr -Override base address (PIE bins) +Override the base address (PIE bins). .It Fl c -List classes +List classes. .It Fl cc -List classes in header format +List classes in header format. .It Fl C Ar fmt:C:D -Create [elf, mach0, pe] with Code and Data hexpairs (see -a) +Create `[elf, mach0, pe]` with Code and Data hex-pairs (see `-a`). .It Fl d -Show debug/dwarf information +Show debug/dwarf information. .It Fl dd -Load debug/dwarf information from debuginfod server +Load debug/dwarf information from a `debuginfod` server. .It Fl D Ar lang name -Demangle symbol name (-D all for bin.demangle=true) +Demangle a symbol name (`-D all` for `bin.demangle=true`). .It Fl e -Entrypoint +Entrypoint. .It Fl E -Globally exportable symbols +Globally exportable symbols. .It Fl f Ar str -Select sub-bin named str +Select a sub-bin named `str`. .It Fl F Ar binfmt -Force to use that bin plugin (ignore header check) +Force the use of that `bin` plugin (ignore the header check). .It Fl g -Same as -SMZIHVResizcld -SS -SSS -ee (show all information) +Same as `-SMZIHVResizcld -SS -SSS -ee` (show all information). .It Fl G Ar addr -Load address . offset to header +Load address, offset to the header. .It Fl h -Show usage help message +Show the usage help message. .It Fl H -Header fields +Header fields. .It Fl i -Import (symbols imported from libraries) +Imports (symbols imported from libraries). .It Fl I -Binary info +Binary info. .It Fl j -Output in JSON +Output in JSON. .It Fl k Ar sdb-query -Run sdb query. for example: '*' +Run an SDB query, for example: `*`. .It Fl K Ar algo -Calculate checksums (md5, sha1, ..) +Calculate checksums (`md5`, `sha1`, etc.). .It Fl l -Linked libraries +Linked libraries. .It Fl L Ar plugin -List supported bin plugins or plugin details +List supported `bin` plugins or plugin details. .It Fl m Ar addr -Show source line at addr +Show the source line at `addr`. .It Fl M -Main (show address of main symbol) +Main (show the address of the `main` symbol). .It Fl n Ar str -Show section, symbol, or import named str +Show a section, symbol, or import named `str`. .It Fl N Ar min:max -Force min:max number of chars per string (see -z and -zz) +Force a `min:max` number of characters per string (see `-z` and `-zz`). .It Fl o Ar str -Output file/folder for write operations (out by default) +Output file/folder for write operations (`out` by default). .It Fl O Ar str -Write/extract operations (-O help) +Write/extract operations (`-O help`). .It Fl p -Show physical addresses +Show physical addresses. .It Fl P -Show debug/pdb information +Show debug/PDB information. .It Fl PP -Download pdb file for binary +Download a PDB file for the binary. .It Fl q -Be quiet, just show fewer data +Be quiet; just show fewer data. .It Fl qq -Show less info (no offset/size for -z for ex.) +Show less info (e.g., no offset/size for `-z`). .It Fl Q -Show load address used by dlopen (non-aslr libs) +Show the load address used by `dlopen` (non-ASLR libs). .It Fl r -Show output in rizin format +Show output in Rizin format. .It Fl R -Show relocations +Show relocations. .It Fl s -Symbols +Symbols. .It Fl S -Sections +Sections. .It Fl SS -Segments +Segments. .It Fl SSS -Sections mapping to segments +Sections mapping to segments. .It Fl T -Display file signature +Display the file signature. .It Fl u -Unfiltered (no rename duplicated symbols/sections) +Unfiltered (do not rename duplicated symbols/sections). .It Fl U -Resources +Resources. .It Fl v -Show version information +Show version information. .It Fl V -Show binary version information +Show binary version information. .It Fl w -Display try/catch blocks +Display `try`/`catch` blocks. .It Fl x -Extract bins contained in file +Extract bins contained in the file. .It Fl X Ar fmt [f] .. -Package in fat or zip the given files and bins contained in file +Package in `fat` or `zip` the given files and bins contained in the file. .It Fl Y Ar fw file -Calculate all the possibles base address candidates of a firmware bin +Calculate all the possible base address candidates of a firmware bin. .It Fl z -Show strings (from data section) +Show strings (from the data section). .It Fl zz -Show strings (from raw strings from bin) +Show strings (from raw strings from the bin). .It Fl zzz -Dump raw strings to stdout (for huge files) +Dump raw strings to `stdout` (for huge files). .It Fl Z -Guess size of binary program +Guess the size of the binary program. .El .Sh ENVIRONMENT .Pp -RZ_BIN_CODESIGN_VERBOSE: make code signatures verbose +`RZ_BIN_CODESIGN_VERBOSE`: Make code signatures verbose. .Pp -RZ_BIN_DEBASE64: e bin.debase64 - try to debase64 all strings +`RZ_BIN_DEBASE64`: `e bin.debase64` - Try to debase64 all strings. .Pp -RZ_BIN_DEBUGINFOD_URLS: e bin.dbginfo.debuginfod_urls - use alternative debuginfod server +`RZ_BIN_DEBUGINFOD_URLS`: `e bin.dbginfo.debuginfod_urls` - Use an alternative `debuginfod` server. .Pp -RZ_BIN_DEMANGLE: e bin.demangle - do not demangle symbols +`RZ_BIN_DEMANGLE`: `e bin.demangle` - Do not demangle symbols. .Pp -RZ_BIN_LANG: e bin.lang - assume lang for demangling +`RZ_BIN_LANG`: `e bin.lang` - Assume a language for demangling. .Pp -RZ_BIN_MAXSTRBUF: e bin.maxstrbuf - specify maximum buffer size +`RZ_BIN_MAXSTRBUF`: `e bin.maxstrbuf` - Specify the maximum buffer size. .Pp -RZ_BIN_PDBSERVER: e pdb.server - use alternative PDB server +`RZ_BIN_PDBSERVER`: `e pdb.server` - Use an alternative PDB server. .Pp -RZ_BIN_PREFIX: e bin.prefix - prefix symbols/sections/relocs with a specific string +`RZ_BIN_PREFIX`: `e bin.prefix` - Prefix symbols/sections/relocs with a specific string. .Pp -RZ_BIN_STRFILTER: e bin.str.filter - rizin -qc 'e bin.str.filter=??' - +`RZ_BIN_STRFILTER`: `e bin.str.filter` - `rizin -qc 'e bin.str.filter=??' -`. .Pp -RZ_BIN_STRPURGE: e bin.str.purge - try to purge false positives +`RZ_BIN_STRPURGE`: `e bin.str.purge` - Try to purge false positives. .Pp -RZ_BIN_SYMSTORE: e pdb.symstore - path to downstream symbol store +`RZ_BIN_SYMSTORE`: `e pdb.symstore` - Path to a downstream symbol store. .Pp -RZ_CONFIG: sdb config file +`RZ_CONFIG`: SDB config file. .Pp -RZ_NOPLUGINS: do not load shared plugins (speedup loading) +`RZ_NOPLUGINS`: Do not load shared plugins (speeds up loading). .Sh EXAMPLES .Pp -List symbols of a program: +List the symbols of a program: .Pp .Nm rz-bin Fl s Ar a.out .Pp -Get offset of symbol: +Get the offset of a symbol: .Pp .Nm rz-bin Fl n Cm _main Ar a.out .Pp -Get entrypoint: +Get the entrypoint: .Pp .Nm rz-bin Fl e Ar a.out .Pp -Load symbols and imports from rizin: +Load symbols and imports from Rizin: .Pp .Nm rizin Fl n Ar /bin/ls .Pp -[0x00000000]> .!rz-bin -prsi $FILE +`[0x00000000]> .!rz-bin -prsi $FILE` .Sh SEE ALSO .Pp .Xr rz-hash(1) , diff --git a/binrz/man/rz-diff.1 b/binrz/man/rz-diff.1 index d449787c17d..d98596acd3a 100644 --- a/binrz/man/rz-diff.1 +++ b/binrz/man/rz-diff.1 @@ -10,95 +10,95 @@ \fIfile0\fR \fIfile1\fR .Sh DESCRIPTION -rz-diff compares two files or binary programs and highlights the differences between them. It supports diffing different aspects like raw bytes, text lines, functions, sections, strings, etc., based on the options used. +`rz-diff` compares two files or binary programs and highlights the differences between them. It supports diffing different aspects, such as raw bytes, text lines, functions, sections, strings, etc., based on the options used. .Pp .Bl -tag -width Fl .It Fl A -Compare virtual addresses from file0 with physical addresses in file1 +Compare virtual addresses from `file0` with physical addresses in `file1`. .It Fl a Ar [arch] -Specify the architecture plugin to use for analysis (e.g., x86, arm) +Specify the architecture plugin to use for analysis (e.g., `x86`, `arm`). .It Fl b Ar [bits] -Specify the register size for the chosen architecture (e.g., 16, 32, 64) +Specify the register size for the chosen architecture (e.g., 16, 32, 64). .It Fl B -Run 'aaa' when loading the binary +Run `aaa` when loading the binary. .It Fl C -Disable the use of colors in the output +Disable the use of colors in the output. .It Fl d Ar [algo] Compute the edit distance between files using the chosen algorithm: .Bl -tag -width .It Ic myers -Eugene W. Myers' O(ND) algorithm (no substitution) +Eugene W. Myers's O(ND) algorithm (no substitution). .It Ic leven -Levenshtein O(N^2) algorithm (with substitution) +Levenshtein O(N^2) algorithm (with substitution). .It Ic ssdeep -Context triggered piecewise hashing comparison +Context-triggered piecewise hashing comparison. .El .It Fl e Ar [k=v] -Set an evaluable config variable +Set an evaluable config variable. .It Fl H -Enable hexadecimal visual mode for comparing files in hexadecimal format +Enable hexadecimal visual mode for comparing files in hexadecimal format. .It Fl h -Display the help message +Display the help message. .It Fl i -Use command line arguments instead of files (only for -d) +Use command-line arguments instead of files (only for `-d`). .It Fl j -Output the comparison results in JSON format +Output the comparison results in JSON format. .It Fl q -Generate quiet output with minimal information +Generate quiet output with minimal information. .It Fl 0 Ar [cmd] -Input for file0 when option -t 'commands' is given +Input for `file0` when the option `-t 'commands'` is given. .It Fl 1 Ar [cmd] -Input for file1 when option -t 'commands' is given +Input for `file1` when the option `-t 'commands'` is given. .It Fl S Ar [WxH] -Set the width and height of the terminal for visual mode +Set the width and height of the terminal for visual mode. .It Fl t Ar [type] Compute the difference between two files based on the specified type: .Bl -tag -width .It Ic bytes -Compare raw bytes in the files (only for small files) +Compare raw bytes in the files (only for small files). .It Ic lines -Compare text files +Compare text files. .It Ic functions -Compare functions found in the files +Compare functions found in the files. .It Ic classes -Compare classes found in the files +Compare classes found in the files. .It Ic command Compare command output returned when executed in both files. -Requires -0 , -1 is optional. +Requires `-0 `; `-1 ` is optional. .It Ic entries -Compare entries found in the files +Compare entries found in the files. .It Ic fields -Compare fields found in the files +Compare fields found in the files. .It Ic graphs -Compare 2 functions and outputs in graphviz/dot format. -Requires -0 , -1 is optional. +Compare 2 functions and output in `graphviz`/`dot` format. +Requires `-0 `; `-1 ` is optional. .It Ic imports -Compare imports found in the files +Compare imports found in the files. .It Ic libraries -Compare libraries found in the files +Compare libraries found in the files. .It Ic sections -Compare sections found in the files +Compare sections found in the files. .It Ic strings -Compare strings found in the files +Compare strings found in the files. .It Ic symbols -Compare symbols found in the files +Compare symbols found in the files. .El .It Fl T -Show timestamp information in the output +Show timestamp information in the output. .It Fl V -Show version information for rz-diff +Show version information for `rz-diff`. .It Fl v -be more verbose (stderr output) +Be more verbose (`stderr` output). .El .Pp -Palette colors can be changed by adding the following lines inside the $HOME/.rizinrc file +Palette colors can be changed by adding the following lines inside the `$HOME/.rizinrc` file: .Bl -tag .It Ic ec diff.unknown blue -offset color +Offset color. .It Ic ec diff.match green -match color +Match color. .It Ic ec diff.unmatch red -mismatch color +Mismatch color. .El .Sh EXAMPLE .Pp diff --git a/binrz/man/rz-esil.7 b/binrz/man/rz-esil.7 index b968fd5f250..2a82a27bdc7 100644 --- a/binrz/man/rz-esil.7 +++ b/binrz/man/rz-esil.7 @@ -3,11 +3,11 @@ ESIL \- Evaluable Strings Intermediate Language .SH DESCRIPTION -ESIL aims to describe a Forth-like representation for every target CPU opcode semantics. ESIL representations can be evaluated (interpreted) in order to emulate individual instructions. +ESIL aims to describe a Forth-like representation for every target CPU's opcode semantics. ESIL representations can be evaluated (interpreted) in order to emulate individual instructions. .SH SYNTAX -Each command of an ESIL expression is separated by a comma +Each command of an ESIL expression is separated by a comma. .IP ,, .IP ,, @@ -15,18 +15,18 @@ Each command of an ESIL expression is separated by a comma .SH BASIC OPERATIONS -These operations should be enough to emulate most instructions of any architecture +These operations should be enough to emulate most instructions of any architecture. .IP = -Set the value of the destination to the value of the source +Set the value of the destination to the value of the source. .IP + -Add the values of source0 and source1 and push the result on the esil stack +Add the values of `source0` and `source1` and push the result on the ESIL stack. .IP - -Subtract the value of source0 from the value of source1 and push the result on the esil stack +Subtract the value of `source0` from the value of `source1` and push the result on the ESIL stack. .IP * -Multiply the values of source0 and source1 and push the result on the esil stack +Multiply the values of `source0` and `source1` and push the result on the ESIL stack. .IP / -Divide the value of source1 by the value of source0 +Divide the value of `source1` by the value of `source0`. .SH BASIC OPERATIONS EXAMPLES (x86) diff --git a/binrz/man/rz-find.1 b/binrz/man/rz-find.1 index d6dbe0cdda4..0edf0102a8f 100644 --- a/binrz/man/rz-find.1 +++ b/binrz/man/rz-find.1 @@ -2,7 +2,7 @@ .Dt RZ_FIND 1 .Sh NAME .Nm rz-find -.Nd Find byte patterns in files +.Nd Find byte patterns in files. .Sh SYNOPSIS .Nm rz-find .Op Fl hijmnrqvxzZ @@ -16,58 +16,58 @@ This command is part of the Rizin project. .Pp .Nm rz-find -Searches for specified byte patterns, strings, or hexpairs in the given files. +Searches for specified byte patterns, strings, or hex-pairs in the given files. .Pp The options are: .Bl -tag -width Fl .It Fl a Ar align -Only accept aligned hits +Only accept aligned hits. .It Fl b Ar size -Set block size +Set the block size. .It Fl e Ar regex -Search for regex matches (can be used multiple times) +Search for regex matches (can be used multiple times). .It Fl f Ar from -Start searching from address 'from' +Start searching from address `from`. .It Fl F Ar file -Read the contents of the file and use it as a keyword +Read the contents of the file and use it as a keyword. .It Fl h -Show usage help message +Show the usage help message. .It Fl i -Identify filetype (rizin -nqcpm file) +Identify the filetype (`rizin -nqcpm file`). .It Fl j -Output in JSON +Output in JSON. .It Fl m -Magic search, file-type carver +Magic search, file-type carver. .It Fl M Ar str -Set a binary mask to be applied on keywords +Set a binary mask to be applied to keywords. .It Fl n -Do not stop the search when a read error occurs +Do not stop the search when a read error occurs. .It Fl r -Print using rizin commands +Print using Rizin commands. .It Fl s Ar str -Search for a specific string (can be used multiple times) +Search for a specific string (can be used multiple times). .It Fl w Ar str -Search for a specific wide string (can be used multiple times). Assumes str is UTF-8 +Search for a specific wide string (can be used multiple times). Assumes `str` is UTF-8. .It Fl I Ar str -Search for an entry in import table +Search for an entry in the import table. .It Fl S Ar str -Search for a symbol in symbol table +Search for a symbol in the symbol table. .It Fl t Ar to -Stop search at address 'to' +Stop the search at address `to`. .It Fl q -Quiet mode - do not show headings (filenames) above matching contents (default for searching a single file) +Quiet mode - do not show headings (filenames) above matching contents (default for searching a single file). .It Fl v -Show version information +Show version information. .It Fl x Ar hex -Search for an hexpair string (can be used multiple times) +Search for a hex-pair string (can be used multiple times). .It Fl X -Show hexdump of search results +Show a hexdump of the search results. .It Fl z -Search for zero-terminated strings +Search for zero-terminated strings. .It Fl Z -Show string found on each search hit +Show the string found on each search hit. .It Fl E Ar command -Execute for each file found. +Execute `` for each file found. .Pp .Sh SEE ALSO .Pp diff --git a/binrz/man/rz-gg.1 b/binrz/man/rz-gg.1 index ac37ee90234..f7c7ae20cd3 100644 --- a/binrz/man/rz-gg.1 +++ b/binrz/man/rz-gg.1 @@ -2,7 +2,7 @@ .Dt RZ_GG 1 .Sh NAME .Nm rz-gg -.Nd rizin frontend for RzEgg, compile programs into tiny binaries for different architectures. +.Nd Rizin frontend for RzEgg; compiles programs into tiny binaries for different architectures. .Sh SYNOPSIS .Nm rz-gg .Op Fl FOLsrxvhz @@ -29,75 +29,75 @@ .Sh DESCRIPTION This command is part of the Rizin project. .Pp -Programs generated by RzEgg are relocatable and can be injected into a running process or on-disk binary file. +Programs generated by RzEgg are relocatable and can be injected into a running process or an on-disk binary file. .Pp -Since the rz-gg-cc merge, rz-gg can now generate shellcodes from C code. The final code can be linked with rz-bin, and it is relocatable, allowing injection into any remote process. This feature is conceptually based on shellforge4, but only supports Linux/OSX x86-32/64 platforms. +Since the `rz-gg-cc` merge, `rz-gg` can now generate shellcodes from C code. The final code can be linked with `rz-bin`, and it is relocatable, allowing injection into any remote process. This feature is conceptually based on `shellforge4` but only supports Linux/macOS x86-32/64 platforms. .Sh DIRECTIVES .Pp -The rrz (rz-gg) configuration file accepts the following directives, described as key=value entries and comments defined as lines starting with '#'. +The `rrz` (`rz-gg`) configuration file accepts the following directives, described as `key=value` entries and comments defined as lines starting with `#`. .Bl -tag -width Fl .It Fl a Ar arch -Select architecture (x86, mips, arm) +Select the architecture (`x86`, `mips`, `arm`). .It Fl b Ar bits -Set register size (32, 64, ..) +Set the register size (32, 64, etc.). .It Fl B Ar hexpairs -Append hexpair bytes +Append hex-pair bytes. .It Fl c Ar k=v -Set configure option for the shellcode encoder. The argument must be key=value +Set a configuration option for the shellcode encoder. The argument must be `key=value`. .It Fl C Ar file -Append contents of file +Append the contents of a file. .It Fl d Ar off:dword -Patch dword (4 bytes) at given offset +Patch a dword (4 bytes) at the given offset. .It Fl D Ar off:qword -Patch qword (8 bytes) at given offset +Patch a qword (8 bytes) at the given offset. .It Fl e Ar encoder -Use specific encoder. See -L +Use a specific encoder. See `-L`. .It Fl f Ar format -Output format (raw, c, pe, elf, mach0, python, javascript) +Output format (`raw`, `c`, `pe`, `elf`, `mach0`, `python`, `javascript`). .It Fl F -Output native format (osx=mach0, linux=elf, ..) +Output in native format (`osx`=`mach0`, `linux`=`elf`, etc.). .It Fl h -Show usage help message +Show the usage help message. .It Fl i Ar shellcode -Include shellcode plugin, use options. See -L +Include a shellcode plugin; use options. See `-L`. .It Fl I Ar path -Add include path +Add an include path. .It Fl k Ar kernel -Operating system's kernel (linux, bsd, osx, w32) +Operating system's kernel (`linux`, `bsd`, `osx`, `w32`). .It Fl L -List all plugins (shellcodes and encoders) +List all plugins (shellcodes and encoders). .It Fl n Ar num32 -Append 32bit number (4 bytes) +Append a 32-bit number (4 bytes). .It Fl N Ar num64 -Append 64bit number (8 bytes) +Append a 64-bit number (8 bytes). .It Fl o Ar file -Output file to write result of compilation +Output file to write the result of the compilation. .It Fl O -Use default output file (filename without extension or a.out) +Use the default output file (filename without extension or `a.out`). .It Fl p Ar padding -Add padding after compilation (padding=n10s32) - ntas : begin nop, trap, 'a', sequence - NTAS : same as above, but at the end +Add padding after compilation (`padding=n10s32`). + `ntas`: begin nop, trap, 'a', sequence + `NTAS`: same as above, but at the end .It Fl P Ar size -Prepend debruijn sequence of given length +Prepend a de Bruijn sequence of the given length. .It Fl q Ar fragment -Debruijn pattern offset +De Bruijn pattern offset. .It Fl r -Show raw bytes instead of hexpairs +Show raw bytes instead of hex-pairs. .It Fl s -Show assembler +Show the assembler. .It Fl S Ar string -Append a string +Append a string. .It Fl v -Show version information +Show version information. .It Fl w Ar off:hex -Patch hexpairs at given offset +Patch hex-pairs at the given offset. .It Fl x -Execute +Execute. .It Fl X Ar hexpairs -Execute rop chain, using the stack provided +Execute a ROP chain, using the stack provided. .It Fl z -Output in C string syntax +Output in C string syntax. .El .Sh EXAMPLE .Pp @@ -130,12 +130,12 @@ Output in C string syntax $ wc \-c < hi 165 .Pp - # The compiled shellcode has zeroes + # The compiled shellcode has zeros $ rz-gg hi.c | tail -1 eb0748656c6c6f0a00bf01000000488d35edffffffba06000000b8010 000000f0531ffb83c0000000f0531c0c3 .Pp - # Use a xor encoder with key 64 to bypass + # Use a XOR encoder with key 64 to bypass $ rz-gg \-e xor \-c key=64 \-B $(rz-gg hi.c | tail -1) 6a2d596a405be8ffffffffc15e4883c60d301e48ffc6e2f9ab4708252 c2c2f4a40ff4140404008cd75adbfbfbffa46404040f8414040404f45 diff --git a/binrz/man/rz-hash.1 b/binrz/man/rz-hash.1 index 2ee87c051f4..3e2e34dac0a 100644 --- a/binrz/man/rz-hash.1 +++ b/binrz/man/rz-hash.1 @@ -2,7 +2,7 @@ .Dt RZ_HASH 1 .Sh NAME .Nm rz-hash -.Nd block based hashing utility +.Nd Block-based hashing utility. .Sh SYNOPSIS .Nm rz-hash .Op Fl vhBkjLq @@ -20,65 +20,65 @@ .Sh DESCRIPTION This program is part of the Rizin project. .Pp -rz-hash allows you to calculate, check and show the hash values of each block of a target file. The block size is 32768 bytes by default. It's allowed to hash from stdin using '-' as a target file. You can compare against a known hash and get the result in the exit status. +`rz-hash` allows you to calculate, check, and show the hash values of each block of a target file. The block size is 32,768 bytes by default. It's allowed to hash from `stdin` using `-` as a target file. You can compare against a known hash and get the result in the exit status. .Pp -You can hash big files by hashing each block and later determine what part of it has been modified. Useful for filesystem analysis. +You can hash large files by hashing each block and later determine what part of it has been modified. Useful for filesystem analysis. .Pp -This command can be used to calculate hashes of a certain part of a file or a command line passed string. +This command can be used to calculate hashes of a certain part of a file or a command-line-passed string. .Pp -This is the command used by the 'ph' command of rizin. +This is the command used by the `ph` command of Rizin. .Bl -tag -width Fl .It Fl v -Show version information +Show version information. .It Fl h -Show usage help message +Show the usage help message. .It Fl -Input read from stdin instead of from a file +Input is read from `stdin` instead of from a file. .It Fl a Ar algo -Hash algorithm to use; you can specify multiple ones by appending a comma (example: sha1,md4,md5,sha256) +The hash algorithm to use; you can specify multiple ones by appending a comma (example: `sha1,md4,md5,sha256`). .It Fl B -Output the calculated value for each block +Output the calculated value for each block. .It Fl b Ar size -Set the block size +Set the block size. .It Fl c Ar value -Compare calculated value with a given one (hexadecimal) +Compare a calculated value with a given one (hexadecimal). .It Fl e Ar endian -Set the endianness (default: 'big'; accepted: 'big' or 'little') +Set the endianness (default: 'big'; accepted: 'big' or 'little'). .It Fl D Ar algo -Decrypt the given input; use -S to set the key and -I to set IV (if needed) +Decrypt the given input; use `-S` to set the key and `-I` to set the IV (if needed). .It Fl E Ar algo -Encrypt the given input; use -S to set the key and -I to set IV (if needed) +Encrypt the given input; use `-S` to set the key and `-I` to set the IV (if needed). .It Fl f Ar from -Start the calculation at the given offset +Start the calculation at the given offset. .It Fl t Ar to -Stop the calculation at the given offset +Stop the calculation at the given offset. .It Fl I Ar iv -Set the initialization vector (IV) +Set the initialization vector (IV). .It Fl i Ar times -Repeat the calculation N times +Repeat the calculation N times. .It Fl j -Output the result as a JSON structure +Output the result as a JSON structure. .It Fl k -Output the calculated value using openssh's randomkey algorithm +Output the calculated value using OpenSSH's `randomkey` algorithm. .It Fl L -List all algorithms +List all algorithms. .It Fl q -Set quiet mode (use -qq to get only the calculated value) +Set quiet mode (use `-qq` to get only the calculated value). .It Fl S Ar seed -Set the seed for -a; use '^' to append it before the input. Use '@' prefix to load it from a file and '-' to read it +Set the seed for `-a`; use `^` to append it before the input. Use the `@` prefix to load it from a file and `-` to read it. .It Fl K Ar key -Set the HMAC key for -a and the key for -E/-D. Use '@' prefix to load it from a file and '-' to read it from stdin (you can combine them) +Set the HMAC key for `-a` and the key for `-E`/`-D`. Use the `@` prefix to load it from a file and `-` to read it from `stdin` (you can combine them). .It Fl s Ar string -Input read from a zero-terminated string instead of from a file +Input is read from a zero-terminated string instead of from a file. .It Fl x Ar hex -Input read from a hexadecimal value instead of from a file +Input is read from a hexadecimal value instead of from a file. .Pp -All the inputs (besides -s/-x/-c) can be hexadecimal or strings if 's:' prefix is specified. +All the inputs (besides `-s`/`-x`/`-c`) can be hexadecimal or strings if the `s:` prefix is specified. .El .Sh DIAGNOSTICS .Ex -std .Pp -When -c is used, exit status 0 indicates a match between the expected and computed hashes +When `-c` is used, an exit status of 0 indicates a match between the expected and computed hashes. .Sh SEE ALSO .Pp .Xr rizin(1) , diff --git a/binrz/man/rz-run.1 b/binrz/man/rz-run.1 index d116f49f187..cf86ead9397 100644 --- a/binrz/man/rz-run.1 +++ b/binrz/man/rz-run.1 @@ -2,7 +2,7 @@ .Dt RZ_RUN 1 .Sh NAME .Nm rz-run -.Nd rizin utility to run programs in custom environments +.Nd Rizin utility to run programs in custom environments. .Sh SYNOPSIS .Nm rz-run .Op [directives] @@ -11,128 +11,128 @@ .Sh DESCRIPTION This command is part of the Rizin project. .Pp -This program is used as a launcher for running programs with different environment, arguments, permissions, directories and overridden default filedescriptors. +This program is used as a launcher for running programs with different environments, arguments, permissions, directories, and overridden default file descriptors. .Pp .Bl -tag -width Fl .It Fl l List all the supported profile options. .Pp .It Fl t -Output a base template profile. Try rz-run -d > profile.rz +Output a base template profile. Try `rz-run -d > profile.rz`. .Pp .It Fl w -Show the terminal name and wait for a connection from another process. Try rz-run stdio= program=/bin/sh +Show the terminal name and wait for a connection from another process. Try `rz-run stdio= program=/bin/sh`. .El .Pp -The program just accepts a single argument which is the filename of the configuration file to run the program. +The program accepts a single argument, which is the filename of the configuration file to run the program. .Pp -It is useful when you have to run a program using long arguments or pass long data to stdin or things like that usually required for exploiting crackmes :) +It is useful when you have to run a program using long arguments or pass long data to `stdin`, or things like that, which are usually required for exploiting crackmes :). .Sh DIRECTIVES .Pp -The rrz (rz-run) configuration file accepts the following directives, described as key=value entries and comments defined as lines starting with '#'. +The `rrz` (`rz-run`) configuration file accepts the following directives, described as `key=value` entries and comments defined as lines starting with `#`. .Bl -tag -width Fl .It Ar arg[0-511] -Set value for argument N passed to the program +Set the value for argument N passed to the program. .It Ar aslr -Enable or disable ASLR +Enable or disable ASLR. .It Ar bits -Set 32 or 64 bit (if the architecture supports it) +Set 32 or 64 bit (if the architecture supports it). .It Ar chdir -Change directory before executing the program +Change the directory before executing the program. .It Ar chroot -Run the program in chroot. requires some previous setup +Run the program in `chroot`. Requires some previous setup. .It Ar core -Set no limit the core file size +Set no limit on the core file size. .It Ar connect -Connect stdin/stdout/stderr to a socket +Connect `stdin`/`stdout`/`stderr` to a socket. .It Ar pty -Use a pty for connection over socket (with connect/listen) +Use a PTY for connection over a socket (with `connect`/`listen`). .It Ar envfile -Set a file with lines like `var=value` to be used as env +Set a file with lines like `var=value` to be used as the environment. .It Ar fork -Used with the listen option, allow to spawn a different process for each connection. Ignored when debugging. +Used with the `listen` option; allows spawning a different process for each connection. Ignored when debugging. .It Ar input -Set string to be passed to the program via stdin +Set a string to be passed to the program via `stdin`. .It Ar libpath -Override path where the dynamic loader will look for shared libraries +Override the path where the dynamic loader will look for shared libraries. .It Ar listen -Bound stdin/stdout/stderr to a listening socket +Bind `stdin`/`stdout`/`stderr` to a listening socket. .It Ar maxstack -Set the maximum size for the stack +Set the maximum size for the stack. .It Ar maxproc -Set the maximum number of processes +Set the maximum number of processes. .It Ar maxfd -Set the maximum number of file descriptors +Set the maximum number of file descriptors. .It Ar nice -Set the niceness level of the process +Set the niceness level of the process. .It Ar preload -Preload a library (not supported on Windows, only linux,osx,bsd) +Preload a library (not supported on Windows; only Linux, macOS, and BSD). .It Ar daemon -Set to false by default, otherwise it will run the program in background, detached from the terminal. +Set to `false` by default; otherwise, it will run the program in the background, detached from the terminal. .It Ar program -Path to program to be executed +Path to the program to be executed. .It Ar pid -Set to true to print the PID of the process to stderr +Set to `true` to print the PID of the process to `stderr`. .It Ar pidfile -Print the PID of the process to the specified file +Print the PID of the process to the specified file. .It Ar runlib -Path to the library to be executed +Path to the library to be executed. .It Ar runlib.fcn -Function name to call from runlib library +Function name to call from the `runlib` library. .It Ar rzpreload -Preload with librz, kill -USR1 to get an rizin shell or -USRZ to spawn a webserver in a thread +Preload with `librz`; `kill -USR1` to get a Rizin shell or `-USRZ` to spawn a webserver in a thread. .It Ar setenv -Set value for given environment variable +Set the value for a given environment variable. .It Ar setegid -Set effective process group id +Set the effective process group ID. .It Ar seteuid -Set effective process uid +Set the effective process UID. .It Ar setgid -Set process group id +Set the process group ID. .It Ar setuid -Set process uid +Set the process UID. .It Ar sleep -Sleep for the given amount of seconds +Sleep for the given amount of seconds. .It Ar stdio=value -Set io streams (stdin, stdout, stderr) to a value +Set I/O streams (`stdin`, `stdout`, `stderr`) to a value. .It Ar stdio=!cmd -Redirect input/output to the process created by the specified command +Redirect input/output to the process created by the specified command. .It Ar stdin -Set stdin, stdout, and stderr streams to the specified value +Set the `stdin`, `stdout`, and `stderr` streams to the specified value. .It Ar stdout -Select file to replace stdout file descriptor +Select a file to replace the `stdout` file descriptor. .It Ar stderr -Select file to replace stderr file descriptor +Select a file to replace the `stderr` file descriptor. .It Ar system -Execute the given command +Execute the given command. .It Ar timeout -Set a timeout +Set a timeout. .It Ar timeoutsig -Signal to use when killing the child because the timeout happens +Signal to use when killing the child because the timeout occurs. .It Ar unsetenv -Unset one environment variable +Unset one environment variable. .El .Sh VALUE PREFIXES -Every value in this configuration file can contain a special +Every value in this configuration file can contain a special prefix: .Pp .Bl -tag -width Fl .It Ar @filename -Slurp contents of file and put them inside the key +Slurp the contents of a file and put them inside the key. .It Ar "text" -Escape characters useful for hex chars +Escape characters useful for hex characters. .It Ar 'string' -Escape characters useful for hex chars +Escape characters useful for hex characters. .It Ar !cmd -Run command to store the output in the variable +Run a command to store the output in the variable. .It Ar :102030 -Parse hexpair string and store it in the variable +Parse a hex-pair string and store it in the variable. .It Ar :!cmd -Parse hexpair string from output of command and store it in the variable +Parse a hex-pair string from the output of a command and store it in the variable. .It Ar %1234 -Parses the input string and returns it as integer +Parses the input string and returns it as an integer. .El .Sh EXAMPLES -Sample rz-run script +Sample `rz-run` script .Pp $ cat foo.rrz #!/usr/bin/rz-run @@ -154,20 +154,20 @@ Connecting a program to a socket .Pp .Nm rz-run Cm program=/bin/ls Cm connect=localhost:9999 .Pp -Debugging a program redirecting io to another terminal +Debugging a program redirecting I/O to another terminal .Pp - ## open a new terminal and type 'tty' to get + ## Open a new terminal and type `tty` to get $ tty ; clear ; sleep 999999 /dev/ttyS010 - ## in another terminal run rizin + ## In another terminal, run Rizin $ rizin \-r foo.rrz -d ls $ cat foo.rrz #!/usr/bin/rz-run stdio=/dev/ttys010 - ## Or you can use -R to set a key=value + ## Or you can use `-R` to set a `key=value` rizin \-R stdio=/dev/ttys010 -d ls .Pp -You can also use the -- flag to specify program and arguments in a more natural way: +You can also use the `--` flag to specify the program and arguments in a more natural way: .Pp .Nm rz-run Cm timeout=2 Ar -- sleep 4 .Pp diff --git a/binrz/man/rz-sign.1 b/binrz/man/rz-sign.1 index 683602815c6..dcb48fcaead 100644 --- a/binrz/man/rz-sign.1 +++ b/binrz/man/rz-sign.1 @@ -2,27 +2,26 @@ .Dt RZ_SIGN 1 .Sh NAME .Nm RZ_SIGN -.Nd rizin signature utility +.Nd Rizin signature utility. .Sh SYNOPSIS .Nm rz-sign .Op Fl acehoqv .Op Fl o Ar outfile .Ar file .Sh DESCRIPTION -rz-sign allows to create and inspect FLIRT code signatures. +`rz-sign` allows creating and inspecting FLIRT code signatures. .Pp .Bl -tag -width Fl .It Fl a -Analyze binary after loading it with RzCore and use -AA to run aaaa instead of aaa. Available only -together with the o option. +Analyze a binary after loading it with RzCore and use `-AA` to run `aaaa` instead of `aaa`. Available only together with the `o` option. .It Fl c -Interpret the input file as a FLIRT signature file and dump the pattern format +Interpret the input file as a FLIRT signature file and dump the pattern format. .It Fl e -Set an evaluable config variable. Available only together with the o option +Set an evaluable config variable. Available only together with the `o` option. .It Fl h -Show usage help message. +Show the usage help message. .It Fl o Ar file.sig -Perform an analysis of a binary and generate FLIRT signatures for all functions inside it +Perform an analysis of a binary and generate FLIRT signatures for all functions inside it. .It Fl q Enable quiet mode. .It Fl v diff --git a/binrz/man/rz-test.1 b/binrz/man/rz-test.1 index 3d71cdf65ea..d63fe074312 100644 --- a/binrz/man/rz-test.1 +++ b/binrz/man/rz-test.1 @@ -2,7 +2,7 @@ .Dt RZ_TEST 1 .Sh NAME .Nm rz-test -.Nd rizin regression testsuite +.Nd Rizin regression test suite. .Sh SYNOPSIS .Nm rz-test .Op Fl qvVnL @@ -11,57 +11,57 @@ .Sh DESCRIPTION This command is part of the Rizin project. .Pp -Run all the rizin-regressions tests matching a specific word in the name. +Run all the Rizin regression tests matching a specific word in the name. .Pp -You need rizin to be available in $PATH. +You need Rizin to be available in your `$PATH`. .Sh OPTIONS .Bl -tag -width Fl .It Fl h -Show usage help message +Show the usage help message. .It Fl v -Show version information +Show version information. .It Fl q -Quiet mode +Quiet mode. .It Fl V -Be verbose +Be verbose. .It Fl i -Interactive mode +Interactive mode. .It Fl n -Do nothing (don't run any test, just load/parse them) +Do nothing (don't run any tests; just load/parse them). .It Fl L -Log mode (better printing for CI, logfiles, etc.) +Log mode (better printing for CI, log files, etc.). .It Fl F Ar dir -Run fuzz tests (open and default analysis) on all files in the given dir +Run fuzz tests (open and default analysis) on all files in the given directory. .It Fl j Ar threads -How many threads to use for running tests concurrently (default is 8) +How many threads to use for running tests concurrently (default is 8). .It Fl r Ar rizin -Set path to rizin executable (default is rizin) +Set the path to the Rizin executable (default is `rizin`). .It Fl m Ar rz-asm -Set path to rz-asm executable (default is rz-asm) +Set the path to the `rz-asm` executable (default is `rz-asm`). .It Fl f Ar file -File to use for JSON tests (default is bins/elf/crackme0x00b) +File to use for JSON tests (default is `bins/elf/crackme0x00b`). .It Fl C Ar dir -Chdir before running rz-test (default follows executable symlink + test/new) +`chdir` before running `rz-test` (the default follows the executable symlink + `test/new`). .It Fl t Ar seconds -Timeout per test (default is 960 seconds) +Timeout per test (default is 960 seconds). .It Fl o Ar file -Output test run information in JSON format to file +Output test run information in JSON format to a file. .It Fl e Ar dir -Exclude a particular directory while testing (this option can appear many times) +Exclude a particular directory while testing (this option can appear many times). .It Fl s Ar num. -Number of expected successful tests +Number of expected successful tests. .It Fl x Ar num -Number of expected failed tests +Number of expected failed tests. .Pp Supported test types: @JSON @unit @fuzz @cmds .El .Sh ENVIRONMENT .Pp -EDITOR: editor to use (eg: "vim") +EDITOR: Editor to use (e.g., `vim`). .Sh USAGE .Pp -Use the -n flag to dont run any test. Just load them. +Use the `-n` flag to not run any tests, but just load them. .Pp $ rz-test -n [rz-test] Loading tests... diff --git a/doc/PACKAGERS.md b/doc/PACKAGERS.md index 27d73ccfcae..37781d7377d 100644 --- a/doc/PACKAGERS.md +++ b/doc/PACKAGERS.md @@ -9,23 +9,23 @@ We will look at each step below. Releases vs Git content -------------- -If you package a Rizin Release, you will find the tarball with all -dependencies used by Rizin in the -[Release page](https://github.com/rizinorg/rizin/releases) and you can go to -the next step in this document. - -If you want to package a particular git version, keep in mind that Rizin uses -meson subprojects to track versions of dependencies. Subprojects are usually -downloaded during the meson setup step, however, if you can't download -additional code while building the package for your distribution you can -pre-download everything with the following command: +If you package a Rizin release, you will find the tarball with all +dependencies used by Rizin on the +[Release page](https://github.com/rizinorg/rizin/releases), and you can then +proceed to the next step in this document. + +If you want to package a particular `git` version, keep in mind that Rizin +uses Meson subprojects to track dependency versions. Subprojects are +usually downloaded during the `meson` setup step; however, if you can't +download additional code while building the package for your distribution, +you can pre-download everything with the following command: ``` $ git clone https://github.com/rizinorg/rizin $ cd rizin $ meson subprojects download ``` -If you want to prepare a special tarball to use within your distribution, -have a look at [`meson dist`](https://mesonbuild.com/Creating-releases.html). +If you want to prepare a special tarball for use within your distribution, +see [`meson dist`](https://mesonbuild.com/Creating-releases.html). See [BUILDING.md][] for more details. @@ -36,41 +36,41 @@ Rizin uses the `meson` build system. Command line flags passed to meson can change how Rizin is built. First, we suggest you use the options `-Dpackager_version=` -and `-Dpackager=` to help us track the version of Rizin users are -using, because these options are used when you run `rizin -v`. In this way -when a user reports an issue and provides his `rizin -v` output, we know -how Rizin was built. Below, you can see an example of how rizin uses the -additional information: +and `-Dpackager=` to help us track the version of Rizin that +users are using, as these options are used when you run `rizin -v`. This +way, when a user reports an issue and provides their `rizin -v` output, we +know how Rizin was built. Below, you can see an example of how Rizin uses +the additional information: ``` rizin 0.2.0-git @ linux-x86-64, package: 0.2.0-git (rizinorg) commit: 84d2892e7210dc3ced88ae006ba5a9502f4847c8, build: 2021-01-29__09:35:03 ``` -Then, to define the base install location for Rizin use the `--prefix` flag when -invoking `meson`. For system installs it is common to use `/usr`. If in doubt, -check your distributions packaging guidelines. +Then, to define the base installation location for Rizin, use the `--prefix` +flag when invoking `meson`. For system installs, it is common to use +`/usr`. If in doubt, check your distribution's packaging guidelines. If you do not use `/usr` as a prefix, you may want to use `-Dlocal=disabled` to avoid `RPATH` in the installed binaries. If you want to specify different directories for binaries, libraries, header -files, etc., you may want to look at `--bindir`, `--libdir`, `--includedir` or -check `meson setup --help` for more options. For extra control over the -directories used by Rizin, have a look at options `rizin_sdb`, -etc. in [meson_options.txt][]. +files, etc., you may want to look at `--bindir`, `--libdir`, +`--includedir`, or check `meson setup --help` for more options. For extra +control over the directories used by Rizin, see the options `rizin_sdb`, +etc., in [meson_options.txt][]. Rizin uses the Capstone disassembly engine and supports versions 3, 4, and 5. For x86/x86_64 architecture, we use the Zydis decoder and disassembler. By default, we use a custom version of Capstone based on v5 and statically link it into the Rizin executables. Some distributions might prefer that a system version of Capstone be dynamically linked at runtime. To do this, use the -`-Duse_sys_capstone=enabled` command line option when running `meson`. -Similarly we statically link Zydis into the Rizin executables. +`-Duse_sys_capstone=enabled` command-line option when running `meson`. +Similarly, we statically link Zydis into the Rizin executables. To dynamically link the system's Zydis at runtime, use the -`-Duse_sys_zydis=enabled` command line option when running `meson`. +`-Duse_sys_zydis=enabled` command-line option when running `meson`. -You can override the version of Capstone Rizin will use by setting -`use_capstone_version` to one of `v4`, `v5`, `v6` or `next`. +You can override the version of Capstone that Rizin will use by setting +`use_capstone_version` to one of `v4`, `v5`, `v6`, or `next`. There are more bundled dependencies that can be swapped out for system versions. At the time of writing, these are: @@ -90,8 +90,8 @@ At the time of writing, these are: See [meson_options.txt][] for a complete list of compile-time options. -Once you are happy with the flags you have passed to `meson` to configure your -build, you need to actually compile Rizin using `ninja`. You can do this with +Once you are happy with the flags you have passed to `meson` to configure +your build, you need to compile Rizin using `ninja`. You can do this with `ninja -C build`. See [BUILDING.md][] for more details. @@ -99,23 +99,23 @@ See [BUILDING.md][] for more details. Packaging --------- -The final step is creating a package from the build outputs. To do this it may -be required to invoke `DESTDIR=$PKGDIR ninja -C build install` based on the -distribution you are targeting. +The final step is to create a package from the build outputs. To do this, it +may be necessary to invoke `DESTDIR=$PKGDIR ninja -C build install`, +depending on the distribution you are targeting. -Recall in the building step how we defined a `--prefix` to choose where the -software was going to be installed? If we just ran `ninja -C build install` -then we would install the software into that prefix, `/usr` using -the example above. That isn't what we want when we are packaging software for -distributions! Defining `DESTDIR` allows us to choose a base location to install -to that isn't our system root. It could be something as simple as `rizin` which -would mean that `ninja` would actually copy our files to `./rizin/usr/**`. +Recall that in the building step, we defined a `--prefix` to choose where the +software would be installed? If we just ran `ninja -C build install`, we +would install the software into that prefix (`/usr` in the example above). +That is not what we want when we are packaging software for distributions. +Defining `DESTDIR` allows us to choose a base location for the installation +that is not our system root. It could be something as simple as `rizin`, +which would mean that `ninja` would copy our files to `./rizin/usr/**`. -There are files we want to include in the package that aren't installed using -`ninja` so we need to add these by hand. +There are files we want to include in the package that are not installed +using `ninja`, so we need to add them by hand. -To do this, we can use `install` to create directories with the desired attributes -and copy the files in. +To do this, we can use `install` to create directories with the desired +attributes and copy the files. For example: @@ -124,17 +124,17 @@ install -dm644 "${destdir}/usr/share/doc/rizin" cp -r doc/* "${destdir}/usr/share/doc/rizin" ``` -Will create a directory `${destdir}/usr/share/doc/rizin`, set the attributes to -`644`, and copy the docs files into that new directory. See -https://wiki.archlinux.org/index.php/File_permissions_and_attributes for more -information about attributes and permissions. +will create a directory, `${destdir}/usr/share/doc/rizin`, set the +attributes to `644`, and copy the doc files into that new directory. See +https://wiki.archlinux.org/index.php/File_permissions_and_attributes for +more information about attributes and permissions. Licenses -------- -As Rizin is trying to use SPDX, if your package needs license/copyright -information, you can use the [REUSE Software](https://reuse.software/) to -extract the license/copyright of all files in the repository. +Since Rizin uses SPDX, if your package needs license/copyright information, +you can use [REUSE Software](https://reuse.software/) to extract the license +and copyright of all files in the repository. Examples -------- @@ -145,14 +145,17 @@ Compatibility ------------- Try to create packages that do not conflict with existing `radare2` packages. -This may require removing some shared files from the Rizin package (like the -esil man page). +This may require removing some shared files from the Rizin package (such as +the `esil` man page). Existing packages ----------------- -OSX: execute `dist/osx/build_osx_package.sh` on a MacOS system to create a .pkg installer in the base directory, named `rizin-${VERSION}.pkg`. -Windows installer: execute `dist/windows/build_windows_installer.ps1` Powershell script on a Windows system to create a .exe installer in `dist/windows/Output`, named `rizin.exe`. +OSX: Execute `dist/osx/build_osx_package.sh` on a macOS system to create a +`.pkg` installer in the base directory, named `rizin-${VERSION}.pkg`. +Windows Installer: Execute the `dist/windows/build_windows_installer.ps1` +PowerShell script on a Windows system to create a `.exe` installer in +`dist/windows/Output`, named `rizin.exe`. [BUILDING.md]: https://github.com/rizinorg/rizin/blob/dev/BUILDING.md diff --git a/doc/RELEASE.md b/doc/RELEASE.md index 947f9f837c9..d0bcfdd0b0d 100644 --- a/doc/RELEASE.md +++ b/doc/RELEASE.md @@ -1,13 +1,14 @@ Release notes =============== -All releases happen from the `stable` branch, while the `dev` branch is used for -continuous development. Release artifacts and testing are done by GitHub -Actions. +All releases are made from the `stable` branch, while the `dev` branch is +used for continuous development. Release artifacts and testing are handled by +GitHub Actions. # Major/Minor release -Handled by making the `stable` branch content the same as the one on `dev`. It -could (and usually does) break API/ABI compatibility with previous versions. +Handled by making the `stable` branch content the same as the content on +`dev`. It could (and usually does) break API/ABI compatibility with +previous versions. git checkout dev git checkout -b stable-merge @@ -19,7 +20,7 @@ could (and usually does) break API/ABI compatibility with previous versions. git branch -D stable-merge # Patch release -Patches needs to first land in `dev` branch and only then they can be +Patches need to first land in the `dev` branch, and only then can they be cherry-picked to `stable`. git cherry-pick @@ -28,10 +29,10 @@ This release is used for smaller patches that do not break the API/ABI. # Submit PR Submit a new PR of your `stable` branch against `origin/stable`. If you have -push access to `origin`, you should create another branch with a different name -and submit anyway a PR for others to review. +push access to `origin`, you should create another branch with a different +name and submit a PR anyway for others to review. # Prepare release notes -Write useful release notes for the new release. They should not be too detailed -but not even too high level. Finding the right balanace is hard. When done, -attach them to the draft release in the GitHub UI. +Write useful release notes for the new release. They should not be too +detailed, but not too high-level either. Finding the right balance is +hard. When done, attach them to the draft release in the GitHub UI. diff --git a/doc/asm_strings.md b/doc/asm_strings.md index 18812356912..bbe636c3377 100644 --- a/doc/asm_strings.md +++ b/doc/asm_strings.md @@ -4,16 +4,16 @@ There are two ways we colorize our asm strings. -1. The generic method. For straight forward ` ` syntax. -2. The custom method. Which allows for way more complicated assembly syntax. +1. The generic method. For straightforward ` ` syntax. +2. The custom method. which allows for much more complicated assembly syntax. In both methods we start by assigning tokens to sub-strings of the asm string. ### Tokenizing -A token itself simply is a reference a sub-string. -So it contains an offset into the asm string where a sub-string starts. -And the length of the sub-string in bytes as well as the token type. +A token is simply a reference to a sub-string. It contains an offset into +the asm string where a sub-string starts, and the length of the sub-string in +bytes, as well as the token type. ```c typedef struct { @@ -57,7 +57,7 @@ This asm string would be split into 7 tokens: | `, ` | 10 | 2 | separator | | `0x10` | 12 | 4 | number | -A vector of those tokens now describes the whole asm string. +A vector of these tokens now describes the entire asm string. ```c typedef struct { @@ -67,33 +67,34 @@ typedef struct { } RzAsmTokenString; ``` -Note the `op_type` member. It should get a `RzAnalysisOpType` assigned to it. -Depending on this type, the coloring of the mnemonic will differ. +Note the `op_type` member. It should have a `RzAnalysisOpType` assigned to +it. Depending on this type, the coloring of the mnemonic will differ. ### Coloring -Coloring the token vector becomes very straight forward. +Coloring the token vector becomes very straightforward. We simply append each token to each other and insert the color escape sequences before and after each sub-string. ### General tokenize method -The general method assumes that the asm string is roughly of the following form: +The general method assumes that the asm string has roughly the following form: ``` ... ``` -This is the standard parsing pattern. It will be applied if no custom patterns are implemented by the asm module. -For parsing details refer to the documentation in the code (see: `tokenize_asm_generic()`). +This is the standard parsing pattern. It will be applied if no custom patterns are implemented by the `asm` module. +For parsing details, refer to the documentation in the code (see `tokenize_asm_generic()`). ### Custom tokenizing of an asm string. -Custom tokenizing of asm strings can be done for complicated or obscure asm strings. +Custom tokenizing of assembly strings can be done for complicated or obscure +assembly strings. -To implement this for an asm module you need to: +To implement this for an `asm` module, you need to: 1. Define regex patterns for each token type. -2. Parse the asm string in the `disassemble()` function of the asm module. +2. Parse the assembly string in the `disassemble()` function of the `asm` module. **Implementation** @@ -127,15 +128,17 @@ static RZ_OWN RzPVector /**/ *get_token_patterns() { Now we can add the regex patterns for each token type and append them to the vector. -The mnemonics of the `bf` assembly are: `while`, `inc`, `dec`, `trap`, `nop`, `invalid` -and `loop`. We treat `ptr` as a register for simplicity. -We also have the separator ` ` and the operation `[]` (reference the value at `ptr`). +The mnemonics of the `bf` assembly are `while`, `inc`, `dec`, `trap`, +`nop`, `invalid`, and `loop`. We treat `ptr` as a register for simplicity. +We also have the separator ` ` and the operation `[]` (which references the +value at `ptr`). Now we add the regex patterns. -Note, the first patterns in the vector are matched first as well. -They have a higher priority. With the correct ordering, you can prevent conflicts between patterns. -You can also add multiple patterns of the same type. Each of which is further up or down in priority. +Note that the first patterns in the vector are also matched first. They have +a higher priority. With the correct ordering, you can prevent conflicts between +patterns. You can also add multiple patterns of the same type, each with a +higher or lower priority. ```c static RZ_OWN RzPVector /**/ *get_token_patterns() { @@ -178,9 +181,9 @@ static RZ_OWN RzPVector /**/ *get_token_patterns() { } ``` -Now we can parse every disassembled asm string into tokens by passing it to `rz_asm_tokenize_asm_regex()`. -The result should be assigned to `RzAsm.asm_toks`. -In our example we do it in `disassemble()`. +Now we can parse every disassembled assembly string into tokens by passing it +to `rz_asm_tokenize_asm_regex()`. The result should be assigned to +`RzAsm.asm_toks`. In our example, we do it in `disassemble()`. ```c // ... @@ -202,21 +205,24 @@ In our example we do it in `disassemble()`. // ... } ``` -If `RzAsm.asm_toks` is not `NULL` the tokens will be used to colorize the asm string. +If `RzAsm.asm_toks` is not `NULL`, the tokens will be used to colorize the +assembly string. The color of the mnemonic token is defined by the operation type. So ensure that `RzAsmTokenString.op_type` is set correctly. ### What for? -For simple syntax the custom method might seem overengineered. +For simple syntax, the custom method might seem over-engineered. -But defining properly which part of an asm string means what, has additional advantages. +But properly defining which part of an assembly string means what has +additional advantages. - Numbers can be extracted from the string and used later. -- If some syntax needs to be manipulated, it is way easier to do this. - Selecting the token with the right type and change it. No raw string operations anymore. -- For complex syntax it will produce beautiful results. +- If some syntax needs to be manipulated, it is much easier to do this. + Select the token with the right type and change it. No more raw string + operations. +- For complex syntax, it will produce beautiful results. Here is an example for the last point. @@ -228,6 +234,6 @@ The custom method: ![hexagon-syntax-regex](img/hexagon-asm-syntax-regex.png) -As you see, the custom method is way more beautiful. +As you can see, the custom method is much more beautiful. Check out `asm_hexagon.c` for an example of the complex patterns used for it. diff --git a/doc/avr.md b/doc/avr.md index be250bc9a6e..2b97ebee5df 100644 --- a/doc/avr.md +++ b/doc/avr.md @@ -1,11 +1,11 @@ -AVR (arduino, atmega128, ..) -============================ +AVR (Arduino, ATmega128, etc.) +=============================== -Install JTAG serial driver: +Install the JTAG serial driver: http://www.wch.cn/download/CH341SER_MAC_ZIP.html -Install SDK from Arduino: +Install the SDK from Arduino: https://www.arduino.cc/en/Main/Software echo 'PATH="/Applications/Arduino.app//Contents/Java/hardware/tools/avr/bin/:$PATH"' >> ~/.profile @@ -14,9 +14,9 @@ Using GDB: (avr-gdb) target remote :4242 -In another terminal now run: +In another terminal, run: rizin -a avr -d gdb://localhost:4242 -NOTE: Right now the avr debugger is pretty broken, the memory and register reads result in in correct data. +NOTE: The AVR debugger is currently quite broken; memory and register reads result in incorrect data. diff --git a/doc/brainfuck.md b/doc/brainfuck.md index c813265eab7..0ba4fdf2300 100644 --- a/doc/brainfuck.md +++ b/doc/brainfuck.md @@ -1,25 +1,26 @@ -Brainfuck support for rizin -======================== +Brainfuck Support for Rizin +=========================== -Plugins for brainfuck: - - `asm.bf` - brainfuck assembler and disassembler - - `debug.bf` - debugger using bfvm - - `analysis.bf` - code analysis for brainfuck - - `bp.bf` - breakpoints support (experimental) +Plugins for Brainfuck: + - `asm.bf` - Brainfuck assembler and disassembler + - `debug.bf` - Debugger using `bfvm` + - `analysis.bf` - Code analysis for Brainfuck + - `bp.bf` - Breakpoint support (experimental) -To debug a brainfuck program: +To debug a Brainfuck program: rizin -D bf bfdbg:///tmp/bf > dc # continue > x@scr # show screen buffer contents -The debugger creates virtual sections for code, data, screen and input. +The debugger creates virtual sections for code, data, screen, and input. -TODO +TODO ---- -- add support for comments, ignore invalid instructions as nops -- enhance io and debugger plugins to generate sections and set arch opts +- Add support for comments; ignore invalid instructions as nops. +- Enhance I/O and debugger plugins to generate sections and set architecture + options. Hello World =========== diff --git a/doc/calling-conventions.md b/doc/calling-conventions.md index e1c9c2d6e0a..2109fe6c8d6 100644 --- a/doc/calling-conventions.md +++ b/doc/calling-conventions.md @@ -1,39 +1,62 @@ -Calling Conventions profiles -============================ +Calling Convention Profiles +=========================== -Rizin uses calling conventions to help in identifying function formal arguments and return types. It is used also as guide for basic function prototype. +Rizin uses calling conventions to help in identifying function formal arguments +and return types. It is also used as a guide for basic function prototypes. Profile grammar =============== -Since the profiles are based on sdb database, Creating one is as simple as creating group of `key=value` pairs in text file. then parsing it into sdb data file. +Since the profiles are based on the SDB database, creating one is as simple as +creating a group of `key=value` pairs in a text file and then parsing it into +an SDB data file. Attribute list ============== Note that you will substitute `x` for the calling convention name you will use. -`default.cc=x` : used to set the default calling convention used for all functions in `RzAnalysis` instance for which this key is set, string of this calling convention `"x"` will be returned for every call of `RZ_API const char *rz_analysis_cc_default(RzAnalysis *analysis)`. +`default.cc=x`: Used to set the default calling convention for all functions +in an `RzAnalysis` instance for which this key is set. The string of this +calling convention, `"x"`, will be returned for every call of +`RZ_API const char *rz_analysis_cc_default(RzAnalysis *analysis)`. -`x=cc`: used to initialize calling convention (think of it as their is calling convention called x). +`x=cc`: Used to initialize a calling convention (think of it as there is a +calling convention called `x`). -`cc.x.name=x`: This one is a bit awkward, it is used internally to improve memory usage by reducing memory consumption No need to worry about it except for calling convention profile will probably break if this one doesn't exist. +`cc.x.name=x`: This one is a bit awkward; it is used internally to improve +memory usage by reducing memory consumption. You don't need to worry about +it, except that the calling convention profile will probably break if this +one doesn't exist. -`cc.x.arg1=reg`, `cc.x.arg2=reg`: used to set the ith argument of this calling convention to register name, feel free to use whatever register name you want to as long as it is supported by the target architecture. Ex: `cc.optlink.arg1=eax` on x86 architecture. +`cc.x.arg1=reg`, `cc.x.arg2=reg`: Used to set the *i*th argument of this +calling convention to a register name. Feel free to use whatever register +name you want, as long as it is supported by the target architecture. Ex: +`cc.optlink.arg1=eax` on the x86 architecture. -`cc.x.argn=stack`: means that all the arguments (or the rest of them in case there was `argi` for any i as counting number) will be stored in stack from left to right. Ex `cc.cdecl.argn=stack`. +`cc.x.argn=stack`: Means that all the arguments (or the rest of them, in case +there was an `argi` for any counting number *i*) will be stored on the stack +from left to right. Ex: `cc.cdecl.argn=stack`. -`cc.x.argn=stack_rev`: same as `cc.x.argn=stack` except for it means argument are passed right to left. Ex: `cc.stdcall.argn=stack_rev` +`cc.x.argn=stack_rev`: Same as `cc.x.argn=stack`, except that it means +arguments are passed from right to left. Ex: `cc.stdcall.argn=stack_rev`. -`cc.x.ret=reg`: used to set where the return value is stored for the given calling convention. +`cc.x.ret=reg`: Used to set where the return value is stored for the given +calling convention. File Path ========= -In order to integrate the calling convention profile you created with the rizin source, few set of conventions should be followed: - -- Store the unparsed sdb file in `path-to-rizin-source/librz/analysis/d`. -- If you want the sdb to be loaded for specific architecture the file name should follow this convention `cc-arch-bits`, for example to create profile that loads automatically for x86 arch with 16 bits call the file `cc-x86-16` -- In the file `path-to-rizin-source/librz/analysis/d/meson.build` add entry `cc-arch-bits` with desired arch and bits and you should be ready to go. +In order to integrate the calling convention profile you created with the +Rizin source, a few conventions should be followed: + +- Store the unparsed SDB file in `path-to-rizin-source/librz/analysis/d`. +- If you want the SDB to be loaded for a specific architecture, the file name + should follow this convention: `cc-arch-bits`. For example, to create a + profile that loads automatically for the x86 architecture with 16 bits, + call the file `cc-x86-16`. +- In the file `path-to-rizin-source/librz/analysis/d/meson.build`, add an + entry for `cc-arch-bits` with the desired architecture and bits, and you + should be ready to go. diff --git a/doc/crosscompile.md b/doc/crosscompile.md index 6bbd7d1b94e..57329e34aa3 100644 --- a/doc/crosscompile.md +++ b/doc/crosscompile.md @@ -1,12 +1,10 @@ # Cross-compilation -As long as you have the compilation tools for your target architecture/system, -you should be able to cross-compile by using meson. +As long as you have the compilation tools for your target architecture and +system, you should be able to cross-compile using Meson. -Please reference the [Cross -compilation](https://mesonbuild.com/Cross-compilation.html) page on the Meson -site. +Please refer to the [Cross-compilation](https://mesonbuild.com/Cross-compilation.html) +page on the Meson site. -You can also have a look at -[BUILDING.md](https://github.com/rizinorg/rizin/blob/dev/BUILDING.md) for an -example about cross-compilation for Android. +You can also see [BUILDING.md](https://github.com/rizinorg/rizin/blob/dev/BUILDING.md) +for an example of cross-compilation for Android. diff --git a/doc/debug-internals.md b/doc/debug-internals.md index 8d87354e74c..704266a5d97 100644 --- a/doc/debug-internals.md +++ b/doc/debug-internals.md @@ -1,65 +1,65 @@ # Rizin Debugger Internals -The debugger is designed using a multi-tiered plug-in architecture that allows -overriding functionality for architecture or platform-specific reasons. +The debugger is designed with a multi-tiered plugin architecture that allows +overriding functionality for architecture- or platform-specific reasons. -The bulk of the debugger functionality within Rizin core is split between the -"io", "reg", "bp", and "debug". More information on the specific files within -the tree follows. +The bulk of the debugger functionality within the Rizin core is split between +the `io`, `reg`, `bp`, and `debug` modules. More information on the specific +files within the tree follows. ## librz/include/r_debug.h This is the main header file for the debugger. It defines all the relevant -structures and top-level functions, APIs, etc. The debugger plug-in API is also +structures, top-level functions, APIs, etc. The debugger plugin API is also defined in here. ## librz/io/p/io_debug.c -In order to interface with Rizin IO, a plug-in is provided. This handles, for +In order to interface with Rizin IO, a plugin is provided. This handles, for example, spawning processes under a debugger. ## librz/reg -The "reg" module provides functionality for reading and writing registers as +The `reg` module provides functionality for reading and writing registers, as well as setting up profiles. (??profiles??) The functionality lives in the following files: (?? why so many files? can this be simplified??) librz/reg/arena.c // ?? used by analysis and debugger - librz/reg/cond.c // condition registers - librz/reg/double.c // support for double-precision floating point numbers + librz/reg/cond.c // Conditional registers + librz/reg/double.c // Support for double-precision floating-point numbers librz/reg/profile.c // ?? used by analysis and debugger librz/reg/reg.c // top-level register specific code (all of rizin) - librz/reg/value.c // dealing with register values - librz/reg/t/p.c // test code for printing general-purpose registers + librz/reg/value.c // Dealing with register values + librz/reg/t/p.c // Test code for printing general-purpose registers librz/reg/t/regdiff.c // ?? test code for? - librz/reg/t/test.c // test code for register handling + librz/reg/t/test.c // Test code for register handling ## librz/bp -The "bp" subsystem of Rizin implements all the necessary details for dealing +The `bp` subsystem of Rizin implements all the necessary details for dealing with breakpoints on any given architecture. It handles managing the list of breakpoints and more. Rizin supports a multitude of different types of breakpoints. (`??` is there a list? sw, hw, and trace? anything else??) - librz/bp/bp.c // main breakpoint management code - librz/bp/io.c // setting and resetting(??) breakpoints - librz/bp/parser.h // header for breakpoint parser (??) - librz/bp/parser.c // code for breakpoint parser (??) - librz/bp/plugin.c // breakpoint plugin management + librz/bp/bp.c // Main breakpoint management code + librz/bp/io.c // Setting and resetting(??) breakpoints + librz/bp/parser.h // Header for breakpoint parser (??) + librz/bp/parser.c // Code for breakpoint parser (??) + librz/bp/plugin.c // Breakpoint plugin management librz/bp/traptrace.c // traptrace (??) - librz/bp/watch.c // watch points (mostly not implemented) + librz/bp/watch.c // Watchpoints (mostly not implemented) -For architecture specific-handling, "bp" delegates various functionality to +For architecture-specific handling, `bp` delegates various functionality to plugins. The interface for these plugins is much simpler than other plugins -used in the Rizin debugger -- they only define which byte sequences represent +used in the Rizin debugger; they only define which byte sequences represent valid breakpoints for a given architecture. librz/bp/p/bp_arm.c // ARM64, ARM, Thumb, Thumb-2 (big/little endians) @@ -74,40 +74,40 @@ valid breakpoints for a given architecture. The main top-level debugger functionality lives here. It aims to abstract away the common code flow and integration into Rizin while delegating more nuanced -system interactions to plug-ins. +system interactions to plugins. librz/debug/arg.c // used by the analysis engine (??) - librz/debug/desc.c // code for handling file descriptors inside an inferior - librz/debug/esil.c // ESIL related debugging code (??) - librz/debug/map.c // top-level API for dealing with memory maps - librz/debug/pid.c // top-level API for dealing with processes - librz/debug/plugin.c // top-level debugger plugin API handling - librz/debug/reg.c // top-level code for register r/w and display - librz/debug/signal.c // top-level functions for signals - librz/debug/snap.c // code for saving, restoring, showing memory snapshots - librz/debug/trace.c // top-level tracing API (counting insn hits, etc) - librz/debug/t/main.c // test code for the debugger API + librz/debug/desc.c // Code for handling file descriptors inside an inferior + librz/debug/esil.c // ESIL-related debugging code (??) + librz/debug/map.c // Top-level API for dealing with memory maps + librz/debug/pid.c // Top-level API for dealing with processes + librz/debug/plugin.c // Top-level debugger plugin API handling + librz/debug/reg.c // Top-level code for register R/W and display + librz/debug/signal.c // Top-level functions for signals + librz/debug/snap.c // Code for saving, restoring, and showing memory snapshots + librz/debug/trace.c // Top-level tracing API (counting instruction hits, etc.) + librz/debug/t/main.c // Test code for the debugger API ## librz/core/cmd_debug.c -Most of the time a debugger is used by a human to try to understand subtle +Most of the time, a debugger is used by a human to try to understand subtle problems with software and/or hardware. That task would be very difficult without a user interface of some kind. The CLI commands exposed to Rizin are -implemented in here. To get more information about this interface, consult the -user manual or try "d?" to get a crash course. +implemented here. To get more information about this interface, consult the +user manual or try `d?` to get a crash course. ## Debugger Plug-Ins -As mentioned before, the platform specific debugger functionality is delegated -to back-end plugins that implement the necessary interactions, protocols, or -otherwise to get the job done. These plug-ins implement the rizin debugger -plug-in API defined in r_debug.h. +As mentioned before, the platform-specific debugger functionality is +delegated to back-end plugins that implement the necessary interactions, +protocols, or otherwise to get the job done. These plugins implement the +Rizin debugger plugin API defined in `r_debug.h`. ### librz/debug/p/debug_bf.c -A debugger plug-in capable of debugging brainfuck code! +A debugger plugin capable of debugging Brainfuck code! librz/debug/p/bfvm.c // Brainfuck VM implementation librz/debug/p/bfvm.h @@ -115,27 +115,27 @@ A debugger plug-in capable of debugging brainfuck code! ### librz/debug/p/debug_bochs.c -A debugger plug-in that utilizes bochs emulator to control execution. +A debugger plugin that utilizes the Bochs emulator to control execution. ### librz/debug/p/debug_esil.c -This debugger plug-in enables debugging and tracing Rizin own intermediate +This debugger plugin enables debugging and tracing Rizin's own intermediate language, Evaluable Strings Intermediate Language (ESIL). ### librz/debug/p/debug_gdb.c -A Rizin debugger plug-in that uses a remote GDB server/stub as its backend. The -protocol parsing itself is located at subprojects/rzgdb. And corresponding IO -plugin is located in librz/io/p/io_gdb.c +A Rizin debugger plugin that uses a remote GDB server/stub as its back end. +The protocol parsing itself is located at `subprojects/rzgdb`. The +corresponding IO plugin is located in `librz/io/p/io_gdb.c`. ### librz/debug/p/debug_native.c -The "native" debugger plug-in is a bit of a doozy. It implements functionality -for debugging on the most common platforms available: Windows, OSX, Linux, and -BSD. Much of the underlying debug API between these platforms are similar and -thus much of the code within this plug-in is shared. The parts that are not -shared are implemented by platform-specific functions that are provided in the -following files: +The "native" debugger plugin is a bit of a doozy. It implements +functionality for debugging on the most common platforms available: Windows, +macOS, Linux, and BSD. Much of the underlying debug API between these +platforms is similar, and thus much of the code within this plugin is shared. +The parts that are not shared are implemented by platform-specific functions +that are provided in the following files: // architecture-specific debugger code librz/debug/p/native/arm.c // unused? @@ -158,7 +158,7 @@ following files: // platform-specific debugger code on Linux librz/debug/p/native/linux/linux_debug.c // main linux-specific debugging code - librz/debug/p/native/linux/linux_debug.h // including cute penguin ascii art + librz/debug/p/native/linux/linux_debug.h // Including cute penguin ASCII art // architecture-specific register handling on Linux (?? what is this format??) librz/debug/p/native/linux/reg/linux-arm.h @@ -173,15 +173,15 @@ following files: librz/debug/p/native/w32.c // !! not used by anything else librz/debug/p/native/maps/windows.c // platform-specific memory map handling librz/debug/p/native/windows/windows_debug.c // main code for win32 debugger plugin - librz/debug/p/native/windows/windows_debug.h // including cute windows ascii art + librz/debug/p/native/windows/windows_debug.h // Including cute Windows ASCII art // platform-specific debugger code on XNU (OSX/iOS/etc) librz/debug/p/native/darwin.c // !! not used by anything else librz/debug/p/native/maps/darwin.c // platform-specific memory map handling librz/debug/p/native/xnu/xnu_debug.c // main XNU-specific debugging code - librz/debug/p/native/xnu/xnu_debug.h // including cute apple ascii art - librz/debug/p/native/xnu/trap_arm.c // ARM family hardware bps (??) - librz/debug/p/native/xnu/trap_x86.c // x86 family hardware bps (??) + librz/debug/p/native/xnu/xnu_debug.h // Including cute Apple ASCII art + librz/debug/p/native/xnu/trap_arm.c // ARM family hardware BPs (??) + librz/debug/p/native/xnu/trap_x86.c // x86 family hardware BPs (??) librz/debug/p/native/xnu/xnu_excthreads.c // additional XNU thread handling librz/debug/p/native/xnu/xnu_threads.c // XNU thread and register handling librz/debug/p/native/xnu/xnu_threads.h @@ -200,8 +200,8 @@ following files: ### librz/debug/p/debug_qnx.c -A debugger plug-in that enables debugging code natively on QNX systems. Corresponding -IO plugin is located in librz/io/p/io_qnx.c +A debugger plugin that enables debugging code natively on QNX systems. The +corresponding IO plugin is located in `librz/io/p/io_qnx.c`. See doc/qnx ### librz/debug/p/debug_rap.c @@ -210,9 +210,10 @@ See doc/rap ### librz/debug/p/debug_winkd.c -A debugger plugin that enables debugging code remotely via WinDbg protocol. -WinDbg protocol parser is located in subprojects/rzwinkd. Corresponding IO -plugin located in librz/io/p/io_winkd.c See doc/winkd. +A debugger plugin that enables debugging code remotely via the WinDbg +protocol. The WinDbg protocol parser is located in `subprojects/rzwinkd`. +The corresponding IO plugin is located in `librz/io/p/io_winkd.c`. See +doc/winkd. ## Conclusion diff --git a/doc/debug.md b/doc/debug.md index bf0d1ac815e..a4498b70af6 100644 --- a/doc/debug.md +++ b/doc/debug.md @@ -1,13 +1,13 @@ # Conditional breakpoints -conditional breakpoints are implemented in the following way: +Conditional breakpoints are implemented in the following way: -- when a breakpoint is hit, the condition is run as a normal command -- if the command returns a value different from zero, execution continue, -- otherwise, execution is stopped at the breakpoint +- When a breakpoint is hit, the condition is run as a normal command. +- If the command returns a value different from zero, execution continues; +- otherwise, execution is stopped at the breakpoint. # Examples of conditional breakpoints -1. ignore breakpoint at address `0x4000ce` for five times: +1. Ignore the breakpoint at address `0x4000ce` for five times: f times=5 (dec_times,f times=`%vi times-1`,?= times) @@ -15,7 +15,7 @@ conditional breakpoints are implemented in the following way: dbC .(dec_times) @ 0x4000ce dc -2. execute until rax==0x31c0 at address `0x4000ce` +2. Execute until `rax` == `0x31c0` at address `0x4000ce`: e cmd.hitinfo=0 (break_rax,f reg_rax=`dr rax`,f test=`%vi reg_rax-0x31c0`,?= test) @@ -23,7 +23,7 @@ conditional breakpoints are implemented in the following way: dbC .(break_rax) @ 0x4000ce dc -3. perform a register tracing dump at address `0x4000ce` +3. Perform a register tracing dump at address `0x4000ce`: e cmd.hitinfo=0 (trace_rax,dr rax,?= 1) diff --git a/doc/flirt.md b/doc/flirt.md index 0a530f1d525..c9ec5c310f9 100644 --- a/doc/flirt.md +++ b/doc/flirt.md @@ -1,46 +1,47 @@ FLIRT ===== -At the moment of writing Rizin supports loading and finding FLIRT -patterns, those files can be generated with the FLIRT tools from IDA. -Rizin doesn't yet supports creating those files. But it supports its -own signature format which can be used to generate signatures and -find them. +At the time of writing, Rizin supports loading and finding FLIRT +patterns. These files can be generated with the FLIRT tools from IDA. +Rizin does not yet support creating those files. However, it supports +its own signature format, which can be used to generate and find +signatures. This document will focus on FLIRT, not the native Rizin 'Zignatures'. -You need the flair tools/ida utilities. Those tools are closed source -and privative, so you should not distribute them. It is probable that -it is not possible to redistribute the .pat or the .sig files. It -doesn't seems to have watermarks. However it's a bit unclear what -licence the file generated should have. Mentioning the files should -be free of copyrighted material (the original libs bytes). That said, -there's a paragraph in [IDA F.L.I.R.T. Technology: In-Depth](https://www.hex-rays.com/products/ida/tech/flirt/in_depth.shtml) +You need the FLIRT tools/IDA utilities. These tools are closed-source +and proprietary, so you should not distribute them. It is probably not +possible to redistribute the `.pat` or `.sig` files. It doesn't seem to +have watermarks. However, it's a bit unclear what license the generated +file should have. The files should be free of copyrighted material (the +original library bytes). That said, there's a paragraph in +[IDA F.L.I.R.T. Technology: In-Depth](https://www.hex-rays.com/products/ida/tech/flirt/in_depth.shtml) -Create the .pat file --------------------- +Create the `.pat` file +--------------------- cd flair/bin/linux ./pelf -p64 /usr/lib/x86_64-linux-gnu/libc.a libc.pat -Create the .sig file (possible collisions): --------------------- +Create the `.sig` file (possible collisions): +-------------------------------------------- ./sigmake -n libc.pat libc.sig -There's little chance libc.sig will be compatible across systems and -libc versions. If libc.exc exists, you need to resolve some functions -conflicts. Prepend a '+' on the lines you're sure you want to keep -(see end of flair/sigmake.txt). Then redo the sigmake command. The -.sig is now ready to be used with Rizin. +There's little chance that `libc.sig` will be compatible across systems and +`libc` versions. If `libc.exc` exists, you need to resolve some function +conflicts. Prepend a `+` on the lines you're sure you want to keep (see +the end of `flair/sigmake.txt`). Then, redo the `sigmake` command. The +`.sig` file is now ready to be used with Rizin. -Using it with rizin: ------------------ +Using it with Rizin: +-------------------- rizin -c 'zF libc.sig' staticbin -refs: +References: +----------- * flair/sigmake.txt * flair/pat.txt diff --git a/doc/gdb.md b/doc/gdb.md index 42a0723a3a1..2f487e596eb 100644 --- a/doc/gdb.md +++ b/doc/gdb.md @@ -1,26 +1,26 @@ -Connecting rizin with gdb -====================== +Connecting Rizin with GDB +========================= -Running gdbserver ------------------ +Running `gdbserver` +------------------- $ gdbserver :2345 /bin/ls (gdb) target remote localhost:2345 -Connecting from rizin ------------------- +Connecting from Rizin +--------------------- $ rizin -D gdb gdb://127.0.0.1:2345 Supported implementations ========================= -rizin have support for connecting to remote GDB instances: +Rizin has support for connecting to remote GDB instances: x86-32 x86-64 arm arm64 sh - winedbg x x - - - - qemu x x ? x - - gdbserver x x ? ? ? + Wine-GDB x x - - - + QEMU x x ? x - + `gdbserver` x x ? ? ? x = supported ? = untested @@ -31,36 +31,41 @@ Supported Commands - read/write memory - Writing or reading memory is implemented through the m/M packet. + Writing or reading memory is implemented through the `m`/`M` packets. - read registers - Reading registers is currently implemented through the packet of the gdb protocol. - It returns the whole register profile at once. + Reading registers is currently implemented through the `` packet of the + GDB protocol. It returns the entire register profile at once. - write registers - There are two ways of writing registers. The first one is through the P packet. - It works like this: `P=` - The second one is the G packet, that writes the whole register Profile at once. - The implementation first tries to use the newer P packet and if it receives a $00# packet (that says not implemented), it tries to write through the G packet. + There are two ways of writing registers. The first one is through the `P` + packet. It works like this: `P=` + The second one is the `G` packet, which writes the entire register profile + at once. The implementation first tries to use the newer `P` packet, and + if it receives a `$00#` packet (which indicates 'not implemented'), it + tries to write through the `G` packet. -- stepping (but this is still the softstep mode and for an unknown reason it sill does not call th gdb_write_register function) +- stepping (but this is still the soft-step mode, and for an unknown reason, + it still does not call the `gdb_write_register` function) Supported Packets: -- `g` : Reads the whole register Profile at once -- `G` : Writes the whole register Profile at once -- `m` : Reads memory -- `M` : Writes memory -- `vCont,v` : continues execution of the binary -- `P` : Write one register +- `g`: Reads the entire register profile at once +- `G`: Writes the entire register profile at once +- `m`: Reads memory +- `M`: Writes memory +- `vCont,v`: Continues execution of the binary +- `P`: Writes one register TODO ---- -- Implement GDBserver to allow other apps use rizin debugger -- Fix that usese the gdb internal stepping version -- Fix softstep, that it finally recoils correct (it just have to reset the eip/rip) -- Add Breakpoints (should be an easy add of the function, because its already implemented in the gdb lib) +- Implement `gdbserver` to allow other apps to use the Rizin debugger. +- Fix the use of the GDB internal stepping version. +- Fix soft-step, so that it finally recovers correctly (it just has to reset + `eip`/`rip`). +- Add breakpoints (should be an easy addition of the function, because it's + already implemented in the GDB library). diff --git a/doc/register_profile.md b/doc/register_profile.md index ee21ef260f7..501c0b0baa5 100644 --- a/doc/register_profile.md +++ b/doc/register_profile.md @@ -2,7 +2,7 @@ Plugins define the registers of an architecture in a big register profile string. -Here an example: +Here is an example: ```c // A comment @@ -25,7 +25,7 @@ Here an example: // ... ``` -Alias and register definitions are required. A single definition is on each new line. +Alias and register definitions are required. Each definition is on a new line. You can find the parsing code in `librz/reg/profile.c`. @@ -39,14 +39,14 @@ A register alias string is of the following form: = ``` -Some alias: +Some aliases: - `PC`: Program Counter - `BP`: Base Pointer - `SP`: Stack Pointer - `A0-A9`: Argument registers 0-9 - `R0-R9`: Return registers 0-9 -Check out the `RzRegisterId` enumeration for more alias. +Check out the `RzRegisterId` enumeration for more aliases. **Registers** @@ -65,7 +65,7 @@ _Tokens_ |-------|---------|------| | sub-type/main-type | Main-types and sub-types can be `GPR`, `FPU` and some more (see `rz_reg.h::RzRegisterType`). The main type always defines to which group/arena the register belongs. || | name | Can be any string, as long as it doesn't contain blank character '\s'. || -| size | Size of the register as a decimal. If it is prefixed with a `'.'` it is interpreted as bits. Otherwise as bytes. || -| byte/bit offset | The offset from the start of the register profile. The register content is written at this offset. If two registers overlap or share the same offset, they will update same data. | This behavior does not work with RzIL currently! The RzIL VM will only use the first of two overlapping registers! If you implement RzIL for an architecture, you cannot let the registers overlap. | -| packed | Size of the register when it is packed. This is a decimal. If it is prefixed with a `'.'` it is interpreted as bits. Otherwise as bytes. || +| size | Size of the register as a decimal. If it is prefixed with a `.` it is interpreted as bits; otherwise, it is interpreted as bytes. || +| byte/bit offset | The offset from the start of the register profile. The register content is written at this offset. If two registers overlap or share the same offset, they will update the same data. | This behavior does not currently work with RzIL. The RzIL VM will only use the first of two overlapping registers. If you implement RzIL for an architecture, you cannot let the registers overlap. | +| packed | The size of the register when it is packed. This is a decimal. If it is prefixed with a `.`, it is interpreted as bits; otherwise, it is interpreted as bytes. || | Comment or flags | Only one of them is possible. Comments are prefixed with a `#`. Flag bits encoded in the register can be any string without a blank character. || diff --git a/doc/release-template.md b/doc/release-template.md index c22b07056a9..13626148ed1 100644 --- a/doc/release-template.md +++ b/doc/release-template.md @@ -1,30 +1,30 @@ # Release checklist template -For each new Rizin release create a new issue on GitHub with this file as its -content. Go step-by-step through it. +For each new Rizin release, create a new issue on GitHub with this file as +its content. Go through it step-by-step. -- [ ] Update `stable` branch in the proper way +- [ ] Update the `stable` branch in the proper way - [ ] Merge `dev` branch into `stable` branch (for major updates). See https://github.com/rizinorg/rizin/blob/dev/doc/RELEASE.md#majorminor-release. - [ ] Cherry-pick relevant commits from `dev` branch into `stable` branch (for patch updates or once `stable` and `dev` have already diverged considerably). See https://github.com/rizinorg/rizin/blob/dev/doc/RELEASE.md#patch-release. - [ ] Update `version` field in [`meson.build`](https://github.com/rizinorg/rizin/blob/dev/meson.build) file. -- [ ] Submit a PR of `stable` branch against `origin/stable`. If you have push access to origin, you should create another branch with a different name and submit anyway a PR for others to review. -- [ ] Ensure that CI on `stable` branch is all green. If not, fix issues and iterate previous steps as necessary. -- [ ] Merge PR so that `origin/stable` is updated with the new content. -- [ ] Manually test that things work well, in particular major changes in the new release. -- [ ] Start preparing release notes by modifying the draft release automatically created by GitHub CI. -- [ ] Check that [Cutter](https://github.com/rizinorg/cutter) works well with the new version of Rizin. If not, fix as necessary and go back to previous steps until everything is ready. Cutter and Rizin should be released at the same time, so both should be in a good state with major issues solved. - - [ ] Cutter can be compiled with new version of Rizin. - - [ ] Basic Cutter functions work well with new version of Rizin. +- [ ] Submit a PR of the `stable` branch against `origin/stable`. If you have push access to `origin`, you should create another branch with a different name and submit a PR anyway for others to review. +- [ ] Ensure that the CI on the `stable` branch is all green. If not, fix the issues and iterate the previous steps as necessary. +- [ ] Merge the PR so that `origin/stable` is updated with the new content. +- [ ] Manually test that things work well, in particular the major changes in the new release. +- [ ] Start preparing the release notes by modifying the draft release automatically created by the GitHub CI. +- [ ] Check that [Cutter](https://github.com/rizinorg/cutter) works well with the new version of Rizin. If not, fix as necessary and go back to the previous steps until everything is ready. Cutter and Rizin should be released at the same time, so both should be in a good state with major issues resolved. + - [ ] Cutter can be compiled with the new version of Rizin. + - [ ] Basic Cutter functions work well with the new version of Rizin. - [ ] Cutter is in good shape to be released. -- [ ] Check that [rz-ghidra](https://github.com/rizinorg/rz-ghidra) works well with the new version of Rizin. If not, fix as necessary and go back to previous steps until everything is ready. -- [ ] Check that [jsdec](https://github.com/rizinorg/jsdec) works well with the new version of Rizin. If not, fix as necessary and go back to previous steps until everything is ready. -- [ ] Check that [rz-retdec](https://github.com/rizinorg/rz-retdec) works well with the new version of Rizin. If not, fix as necessary and go back to previous steps until everything is ready. -- [ ] Check that [rizin-extras](https://github.com/rizinorg/rizin-extras/) and rz-keystone in particular works well with the new version of Rizin. If not, fix as necessary and go back to previous steps until everything is ready. -- [ ] Check that core plugins in [rz-pm-db](https://github.com/rizinorg/rz-pm-db) can be installed correctly with the new version of Rizin. If not, fix as necessary and go back to previous steps until everything is ready. -- [ ] Replace `RZ_PIPE_PY_VERSION` and `RZ_GHIDRA_VERSION` in [`Dockerfile`](https://github.com/rizinorg/rizin/blob/dev/Dockerfile) with the right commits from those repositories. Merge the commit with the Rizin changes in the `stable` branch. -- [ ] Quick test again that Rizin and Cutter work together. +- [ ] Check that [rz-ghidra](https://github.com/rizinorg/rz-ghidra) works well with the new version of Rizin. If not, fix as necessary and go back to the previous steps until everything is ready. +- [ ] Check that [jsdec](https://github.com/rizinorg/jsdec) works well with the new version of Rizin. If not, fix as necessary and go back to the previous steps until everything is ready. +- [ ] Check that [rz-retdec](https://github.com/rizinorg/rz-retdec) works well with the new version of Rizin. If not, fix as necessary and go back to the previous steps until everything is ready. +- [ ] Check that [rizin-extras](https://github.com/rizinorg/rizin-extras/), and `rz-keystone` in particular, works well with the new version of Rizin. If not, fix as necessary and go back to the previous steps until everything is ready. +- [ ] Check that core plugins in [rz-pm-db](https://github.com/rizinorg/rz-pm-db) can be installed correctly with the new version of Rizin. If not, fix as necessary and go back to the previous steps until everything is ready. +- [ ] Replace `RZ_PIPE_PY_VERSION` and `RZ_GHIDRA_VERSION` in the [`Dockerfile`](https://github.com/rizinorg/rizin/blob/dev/Dockerfile) with the correct commits from those repositories. Merge the commit with the Rizin changes in the `stable` branch. +- [ ] Quickly test again that Rizin and Cutter work together. - [ ] Finalize release notes. -- [ ] Release Rizin and Cutter by making their release public on GitHub. +- [ ] Release Rizin and Cutter by making their releases public on GitHub. - [ ] Tag rz-pipe for the new version. - [ ] Tag [rz-bindgen](https://github.com/rizinorg/rz-bindgen) for the new version. - [ ] Tag rz-ghidra for the new version. diff --git a/doc/rzil.md b/doc/rzil.md index b247d5d400e..3527aa64e6c 100644 --- a/doc/rzil.md +++ b/doc/rzil.md @@ -9,91 +9,92 @@ with minor deviations where necessary. Background ---------- -RzIL was introduced as a consequence of dissatisfaction with certain properties -of ESIL, in particular its highly ambiguous and weak typing, requiring [major +RzIL was introduced as a consequence of dissatisfaction with certain +properties of ESIL, in particular its highly ambiguous and weak typing, which +required [major hacks](https://github.com/rizinorg/rizin/blob/2e065789a70edd20909aadcdf7f9c45b9af699fb/librz/analysis/esil/esil.c#L1025-L1032), -for example to determine the bit-width of a value required for further +for example, to determine the bit-width of a value required for further calculations. -At this point, two options to proceed were to either enhance ESIL and -redesign some aspects of it, such as introducing static typing, or starting -from scratch with a new language, preferably reusing an already existing -field-tested one. It was decided for the latter approach, and the language was -chosen to be BAP Core Theory. The initial implementation was then carried out as -part of the Rizin Summer of Code 2021 by heersin. +At this point, two options were considered: either enhance ESIL and redesign +some aspects of it, such as introducing static typing, or start from scratch +with a new language, preferably by reusing an already existing, field-tested +one. The latter approach was chosen, and the language selected was BAP Core +Theory. The initial implementation was then carried out as part of the Rizin +Summer of Code 2021 by heersin. Language Design --------------- -An expression, or "op", in RzIL forms a tree, optionally composed from multiple -sub-ops. All these ops are statically typed and are divided into pure ops and -effects at the highest level. +An expression, or "op," in RzIL forms a tree, optionally composed of +multiple sub-ops. All these ops are statically typed and are divided into +pure ops and effects at the highest level. ### Pure Ops -As the name suggests, pure ops, stored by `RzILOpPure`, are computations that -are free from side-effects and evaluate to a single value. The types of values -supported at the moment are booleans and bitvectors. +As the name suggests, pure ops, stored by `RzILOpPure`, are computations +that are free from side effects and evaluate to a single value. The types +of values supported at the moment are booleans and bitvectors. ### Effect Ops and State As the counterpart to pure ops, effects stored by `RzILOpEffect` express -transitions from one virtual machine state to another. The state of the RzIL vm -consists of variables, binding values to names, and memories, which are arrays -of bitvectors indexed by bitvectors. An example of an effect op is `set n x`, -which sets the value of the variable `n` to the value that the pure expression -`x` evaluates to. The `seq` op allows composing a sequence of multiple effects -to be executed after each other, `branch` introduces conditional execution and -`repeat` enables looping. +transitions from one virtual machine state to another. The state of the RzIL +VM consists of variables, binding values to names, and memories, which are +arrays of bitvectors indexed by bitvectors. An example of an effect op is +`set n x`, which sets the value of the variable `n` to the value that the +pure expression `x` evaluates to. The `seq` op allows composing a sequence +of multiple effects to be executed one after another, `branch` introduces +conditional execution, and `repeat` enables looping. Deviations from Core Theory --------------------------- -Core Theory is very tightly integrated into the BAP ecosystem and while -theoretically being reusable outside as-is, has certain properties that do not +Core Theory is very tightly integrated into the BAP ecosystem and, while +theoretically reusable outside as-is, has certain properties that do not translate well to our C implementation, which is where some deliberate -deviations were made. -The following paragraphs dive deeply into certain implementation details of BAP, -in order to distinguish them from RzIL, so basic knowledge of OCaml or other -ML-like languages is required. This chapter may not be relevant to users only -interested in RzIL. +deviations were made. The following paragraphs dive deeply into certain +implementation details of BAP in order to distinguish them from RzIL, so +basic knowledge of OCaml or other ML-like languages is required. This +chapter may not be relevant to users only interested in RzIL. ### Typing -BAP makes heavy use of OCaml's strong type system to ensure well-typedness also -on the IL level. In particular, any Core Theory expression that is well-typed in -OCaml is automatically well-typed on the level of the IL. +BAP makes heavy use of OCaml's strong type system to ensure well-typedness on +the IL level as well. In particular, any Core Theory expression that is +well-typed in OCaml is automatically well-typed on the IL level. As a specific example, BAP uses the OCaml type `'s bitv` to express pure -bitvector ops, where the size of the bitvector is statically given by the type -variable `'s`. This ensures for example that the op `add : 's bitv -> 's bitv -> -'s bitv` will only be able to take bitvectors of identical size as operands and -return a bitvector of the same size as well. At the same time, it is possible to -have polymorphic ops such as the if-then-else `ite : bool -> 'a pure -> 'a pure --> 'a pure` which can operate on both `bool` and `'s bitv` values (`bool` is an -alias for `Bool.t pure` and `'s bitv` is an alias for `'s Bitv.t pure`). - -Replicating all of this is close to impossible using C's type system, so RzIL -partially relies on dynamic typing on C level, while still keeping static typing -on IL level. In C, RzIL statically separates `RzILOpPure` and `RzILOpEffect`, -but goes no further than that. The typedefs `RzILOpBitVector` and `RzILOpBool` -are mere aliases of `RzILOpPure` to indicate which type is meant whenever it is -known in the code. Further splitting is not possible while keeping ops like -`ite` polymorphic. - -So far, this is only an implementation detail, but does not actually affect the -language itself. However, as there are also certain limitations of OCaml's type -system, our dynamic typing does open up other possibilities. - -For instance, the `append` op is used for appending two bitvectors of arbitrary -sizes. Intuitively, the result's size would be the operands' numbers of bits -added together, motivating a signature that would look somewhat like this: -`append : 'b bitv -> 'c bitv -> ('b + 'c) bitv`. This however is simply not -possible in OCaml, so BAP resorts to specify the result size explicitly as an -argument and defines `append`'s semantics to apply an extra cast after -appending: `append : 'a Bitv.t Value.sort -> 'b bitv -> 'c bitv -> 'a bitv`. -This solves the problem of typing, but makes the op's semantics somewhat -more complicated. +bitvector ops, where the size of the bitvector is statically given by the +type variable `'s`. This ensures, for example, that the op `add : 's bitv -> +'s bitv -> 's bitv` will only be able to take bitvectors of identical size +as operands and will also return a bitvector of the same size. At the same +time, it is possible to have polymorphic ops such as the if-then-else `ite : +bool -> 'a pure -> 'a pure -> 'a pure`, which can operate on both `bool` and +`'s bitv` values (`bool` is an alias for `Bool.t pure`, and `'s bitv` is an +alias for `'s Bitv.t pure`). + +Replicating all of this is nearly impossible using C's type system, so RzIL +partially relies on dynamic typing on the C level while still keeping static +typing on the IL level. In C, RzIL statically separates `RzILOpPure` and +`RzILOpEffect`, but goes no further than that. The typedefs `RzILOpBitVector` +and `RzILOpBool` are mere aliases of `RzILOpPure` to indicate which type is +meant whenever it is known in the code. Further splitting is not possible +while keeping ops like `ite` polymorphic. + +So far, this is only an implementation detail and does not actually affect +the language itself. However, as there are also certain limitations of +OCaml's type system, our dynamic typing does open up other possibilities. + +For instance, the `append` op is used for appending two bitvectors of +arbitrary sizes. Intuitively, the result's size would be the operands' +numbers of bits added together, motivating a signature that would look +something like this: `append : 'b bitv -> 'c bitv -> ('b + 'c) bitv`. This, +however, is simply not possible in OCaml, so BAP resorts to specifying the +result size explicitly as an argument and defines `append`'s semantics to +apply an extra cast after appending: `append : 'a Bitv.t Value.sort -> 'b +bitv -> 'c bitv -> 'a bitv`. This solves the problem of typing but makes +the op's semantics somewhat more complicated. In contrast, RzIL's `append` always has the resulting size as the sum of the operand sizes, simplifying the semantics. @@ -112,36 +113,38 @@ type ident = ``` `Reg` vars, identified by a string, which usually correspond to physical -registers of the emulated architecture, exist in the same way in RzIL as "global -variables". They are defined as part of the vm setup and their scope is -infinite. +registers of the emulated architecture, exist in the same way in RzIL as +"global variables". They are defined as part of the VM setup, and their +scope is infinite. -`Let` vars, which are immutable variables occuring as part of the pure `let` op, -are implemented in a very similar way too. The only difference is that RzIL -again uses string identifiers instead of integers. Their scope is naturally -limited to the body of the `let` expression. As part of the RzIL vm, these -variables are called "local pure variables". +`Let` vars, which are immutable variables occurring as part of the pure `let` +op, are implemented in a very similar way as well. The only difference is +that RzIL again uses string identifiers instead of integers. Their scope is +naturally limited to the body of the `let` expression. As part of the RzIL +VM, these variables are called "local pure variables". `Var` vars in Core Theory are so-called virtual variables, used mostly for -temporary scratch locations. Their scope is unlimited, but when an instruction -is lifted to Core Theory as part of the BAP Knowledge Base (this is -approximately a very innovative kind of database), +temporary scratch locations. Their scope is unlimited, but when an +instruction is lifted to Core Theory as part of the BAP Knowledge Base (this +is approximately a very innovative kind of database), [fresh](https://github.com/BinaryAnalysisPlatform/bap/blob/92d67c83fe0988b8a25bf563bdf33a9594db3e54/lib/bap_core_theory/bap_core_theory_var.ml#L99-L101) temporary variables are always chosen with a globally unique identifier, thus automatically distinguishing temporary variables from multiple lifted instructions. Without the Knowledge Base concept, this approach does not work -for RzIL. Instead, it has "local variables", which are defined simply by the -occurences of `set` ops for their names. Their scope is generally limited to a -single lifted instruction. Even though they are defined implcitly by `set` ops, -they are still typed statically and code with multiple `set` ops assigning -values of different types to the same identifier is considered invalid. +for RzIL. Instead, it has "local variables," which are defined simply by the +occurrences of `set` ops for their names. Their scope is generally limited to +a single lifted instruction. Even though they are defined implicitly by `set` +ops, they are still typed statically, and code with multiple `set` ops +assigning values of different types to the same identifier is considered +invalid. ### Omitted Ops -Not every single Core Theory op has been implemented in RzIL so far. Some may be -implemented later when needed, others do not exist as "real" ops, but only have -a constructor function, composing it from other ops, like the current -implementation of [`unsigned`](https://github.com/rizinorg/rizin/blob/4487d7e1ac8ec0346f0f0b6f14dfdc7d5e424b34/librz/il/il_opcodes.c#L306-L309). +Not every single Core Theory op has been implemented in RzIL so far. Some may +be implemented later when needed; others do not exist as "real" ops but only +have a constructor function, composing them from other ops, like the current +implementation of +[`unsigned`](https://github.com/rizinorg/rizin/blob/4487d7e1ac8ec0346f0f0b6f14dfdc7d5e424b34/librz/il/il_opcodes.c#L306-L309). And some may be omitted completely, such as [`concat`](http://binaryanalysisplatform.github.io/bap/api/master/bap-core-theory/Bap_core_theory/Theory/module-type-Basic/index.html#val-concat), as list operands would be rather awkward to handle in C. @@ -152,12 +155,12 @@ Execution of real machine code The bare IL described above is located in the `il` module. It comes with a reference interpreter implemented as `RzILVM`, which may be used to evaluate arbitrary pure and effect ops on a state of variables and memories. At this -point the IL does not have any connection to real architectures yet. +point, the IL does not have any connection to real architectures yet. -The `analysis` module then bridges exactly this gap. It provides the extended -`RzAnalysisILVM`, which directly builds on top of `RzILVM`, but adds the -connection to `RzIO` for memories, binding of IL variables to machine registers -and other related aspects. +The `analysis` module then bridges exactly this gap. It provides the +extended `RzAnalysisILVM`, which builds directly on top of `RzILVM` but adds +the connection to `RzIO` for memories, the binding of IL variables to +machine registers, and other related aspects. An `RzAnalysisPlugin`, which is used to disassemble instructions of a specific architecture, may also implement lifting from its raw machine code to RzIL in diff --git a/doc/rzshell.md b/doc/rzshell.md index ff4b7ee4bd0..01782cc98c8 100644 --- a/doc/rzshell.md +++ b/doc/rzshell.md @@ -1,12 +1,12 @@ # Command parsing and command handling -The Rizin shell language is originally derived from the Radare2 shell language. +The Rizin shell language is derived from the radare2 shell language. There is a parser generated with [tree-sitter](https://tree-sitter.github.io/tree-sitter/), which allows you to write grammars in JavaScript. You can see our grammar [here](https://github.com/rizinorg/rizin/blob/dev/subprojects/rizin-shell-parser/grammar.js). -The parser recognizes the entire syntax of the rizin shell language, -like: +The parser recognizes the entire syntax of the Rizin shell language, such +as: - [basic statements](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/subprojects/rizin-shell-parser/grammar.js#L238): ` ... ` - [temporary modifier statements](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/subprojects/rizin-shell-parser/grammar.js#L98): ` @ @a:x86:32`, etc. @@ -15,48 +15,51 @@ like: - [grep statements](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/subprojects/rizin-shell-parser/grammar.js#L148): `~` - and many others -These patterns deal with the structure of the rizin shell language, but -they don't parse the input of each specific command available in the rizin shell -(e.g. `af`, `pd`, etc.). The parser just splits the input statement into a -"command name" and a list of "arguments". +These patterns deal with the structure of the Rizin shell language, but +they don't parse the input of each specific command available in the Rizin +shell (e.g., `af`, `pd`, etc.). The parser just splits the input statement +into a "command name" and a list of "arguments". ### Commands registry -The parser alone already provides better consistency with regards to how the -shell behaves, as all commands are split in the same way and it has a more rigid -behavior. However it was also essential to have a global commands registry, -where a command could be registered together with all the information associated -with it, like help messages, description, etc.. +The parser alone already provides better consistency with regard to how the +shell behaves, as all commands are split in the same way and it has more +rigid behavior. However, it was also essential to have a global commands +registry where a command could be registered along with all the +information associated with it, such as help messages, descriptions, etc. -The module +The [`RzCmd`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/include/rz_cmd.h) -is the one in charge of dealing with commands. It provides API to register a new -"command descriptor" (called +module is in charge of dealing with commands. It provides an API to +register a new "command descriptor" (called [`RzCmdDesc`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/include/rz_cmd.h#L388)), -deregister it, call the right command descriptor handler based on a list of -command name + arguments, get the help of a command and potentially do many -other things. +deregister it, call the correct command descriptor handler based on a list +of command names and arguments, get the help for a command, and potentially +do many other things. -As rizin commands mainly form a tree, `RzCmdDesc` are organized in a -tree, with each descriptor having references to its parent and its children. +As Rizin commands mainly form a tree, `RzCmdDesc` are organized in a tree, +with each descriptor having references to its parent and its children. Moreover, a descriptor has its help messages and its handler. To make the retrieval of the right command easier, they are also stored in a -hashtable, using their names as keys. +hash table, using their names as keys. ## How to write a new command? -Let's make an example and suppose we want to add the `sky` command, which -would find all occurrences of the word "sky" in a binary. The first thing to -do is to see where `sky` command could be added by reading +Let's take an example and suppose we want to add the `sky` command, which +would find all occurrences of the word "sky" in a binary. The first thing +to do is to see where the `sky` command could be added by reading [`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_descs.yaml). -`sky` is `s` command's subcommand and they are splitted and placed inside the .YAML -file specified by the descriptor `subcommands` of the respective command. Since `sky` -starts with an `s`, its subcommands would be in [`librz/core/cmd_descs/cmd_seek.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_seek.yaml). -That file respects the same tree structure used when executing rizin and seeing its help, -so it should be simple to see where to place it. If we want to place it under the -`s` sub-tree, we just need to define the descriptors for the command with at least -`name`, `cname`, `summary` and a list of `args` accepted by the command. +`sky` is a subcommand of the `s` command, and they are split and placed +inside the `.YAML` file specified by the `subcommands` descriptor of the +respective command. Since `sky` starts with an `s`, its subcommands would be +in +[`librz/core/cmd_descs/cmd_seek.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_seek.yaml). +That file respects the same tree structure used when executing Rizin and +seeing its help, so it should be simple to see where to place it. If we want +to place it under the `s` sub-tree, we just need to define the descriptors +for the command with at least `name`, `cname`, `summary`, and a list of `args` +accepted by the command. Now we need to choose what kind of command (`type` field in YAML) we want to have. We can see the various types in the @@ -67,7 +70,7 @@ one, so no action is required in this regard. If our new `sky` command accepts a numeric argument, we can specify it in the `args` list, by using the type `RZ_CMD_ARG_TYPE_NUM`. -Then we only need to write the actual code that performs the command's job. +Then, we only need to write the actual code that performs the command's job. You have to call it according to the `cname` field you previously set for the `sky` command, appending `_handler` to that string. @@ -95,7 +98,7 @@ RZ_IPI RzCmdStatus rz_sky_handler(RzCore *core, int argc, const char **argv) { } ``` -The YAML file is used at built-time (by meson only) to autogenerate two +The YAML file is used at build time (by Meson only) to auto-generate two files: `cmd_descs.c` and `cmd_descs.h`. ## Where is the handler of command `x`? @@ -103,12 +106,13 @@ files: `cmd_descs.c` and `cmd_descs.h`. You can use the script `sys/rzshell_which.py` to get the name of the function handling the specified command. -If that doesn't work, please report the problem to us! However, you can still -find the handler yourself by looking at the file +If that doesn't work, please report the problem to us. However, you can +still find the handler yourself by looking at the file [`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_descs.yaml). -By looking at the `cname` field of the command descriptor, you can see what is -the name of the handler of the `x` command. It is always of the form `rz__handler`. -So for the command `x` with `cname = hex` the handler is `rz_hex_handler`. +By looking at the `cname` field of the command descriptor, you can see the +name of the handler of the `x` command. It is always of the form +`rz__handler`. So for the command `x` with `cname = hex`, the handler +is `rz_hex_handler`. Some examples: - command: `wv`, type: unspecified (default to `RZ_CMD_DESC_TYPE_ARGV`), handler: `rz_write_value_handler` @@ -118,14 +122,16 @@ Some examples: Find the command in [`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_descs.yaml), -then fix/improve the `summary` and/or `description` fields. If the command cannot be directly found in `cmd_descs.yaml`, look for the other files in `librz/core/cmd_descs`. +then fix or improve the `summary` and/or `description` fields. If the +command cannot be found directly in `cmd_descs.yaml`, look for the other +files in `librz/core/cmd_descs`. ## How to show examples of a command or additional details -You may notice some commands like `e`, `w` and others have additional -sections where you can show more extensive help with `??` e.g. `e??` (or `w??` etc.). -Those additional sections are called `details` and they can be seen in -existing commands e.g.: +You may notice that some commands, like `e`, `w`, and others, have +additional sections where you can show more extensive help with `??` (e.g., +`e??` or `w??`, etc.). These additional sections are called `details`, and +they can be seen in existing commands, e.g.: https://github.com/rizinorg/rizin/blob/c4a1a501fa9e998aec26005829d391dad3a30dca/librz/core/cmd_descs/cmd_eval.yaml#L14-L31 Their structure is explained at the beginning of [`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/c4a1a501fa9e998aec26005829d391dad3a30dca/librz/core/cmd_descs/cmd_descs.yaml#L27-L29). A _possible_ difference between `?` and `??` is shown below: diff --git a/doc/siol.md b/doc/siol.md index 507b2b0525c..d03da08ddc5 100644 --- a/doc/siol.md +++ b/doc/siol.md @@ -1,13 +1,13 @@ SIOL - Simple IO Layer ====================== -Top-Down-View of siol +Top-Down View of SIOL --------------------- +==================+ | Write-Mask | +==================+ - | Buffer | <--- maybe this could be deprecated, I see no usecase for the buffer + | Buffer | <--- maybe this could be deprecated; I see no use case for the buffer +==================+ | Cache (V) | +==================+ +========================+ @@ -23,7 +23,9 @@ Top-Down-View of siol Maps ---- -every map has a mapid which is a unique identifier. Code from the outside of RIO shall use this id instead of a pointer. This may cost performance, but pointers can hurt you. +Every map has a `mapid`, which is a unique identifier. Code from outside of +RIO shall use this ID instead of a pointer. This may cost performance, but +pointers can be dangerous. Mapping information in the map: @@ -34,7 +36,7 @@ Mapping information in the map: Section Transformation ---------------------- -atm there are 3 diffent transformation-targets: +At the moment, there are 3 different transformation targets: - Hexeditor - Analysis @@ -55,23 +57,30 @@ A section can be related to 2 maps: Hexeditor-Transformation: -- check if addr != vaddr, if so continue -- create a map with the size of min (size, vsize), that maps the to fd corresponding desc to vaddr, starting at addr -- filemap is set to the id of the map -- memmap stays 0 +- check if `addr` != `vaddr`; if so, continue +- create a map with the size of `min(size, vsize)`, that maps the descriptor + corresponding to `fd` to `vaddr`, starting at `addr` +- `filemap` is set to the id of the map +- `memmap` stays 0 Analysis-Transformation: -- when vsize <= size perform Hexeditor-Transformation, and you're done -- create a map with the size of size, that the to fd corresponding vaddr, starting at addr -- filemap is set to the id of the map -- open a new desc, using the null-plugin, with the size of vsize - size -- create another map with the size of vsize - size, that maps the new desc to vaddr + size, starting at 0x0 -- memmap is set to the id of the second map +- when `vsize` <= `size`, perform the Hexeditor-Transformation, and you're done +- create a map with the size of `size`, that maps the `vaddr` corresponding to + `fd`, starting at `addr` +- `filemap` is set to the id of the map +- open a new descriptor, using the `null-plugin`, with the size of `vsize` - `size` +- create another map with the size of `vsize` - `size`, that maps the new + descriptor to `vaddr` + `size`, starting at `0x0` +- `memmap` is set to the id of the second map Emulation-Transformation: -- when the section does not allow write-access perform Analysis-Transformation, and you're done -- open a new desc with write-permissions, using the malloc-plugin, with the size of vsize -- copy min (size, vsize) bytes fram the desc, that fd referes to, starting at addr, to the new desc, starting at 0x0 -- create a map with the size of vsize, that maps the new desc to vaddr, starting at 0x0 +- when the section does not allow write access, perform the + Analysis-Transformation, and you're done +- open a new descriptor with write permissions, using the `malloc-plugin`, with + the size of `vsize` +- copy `min(size, vsize)` bytes from the descriptor that `fd` refers to, + starting at `addr`, to the new descriptor, starting at `0x0` +- create a map with the size of `vsize`, that maps the new descriptor to + `vaddr`, starting at `0x0` diff --git a/doc/windbg.md b/doc/windbg.md index 8b7629c00d4..03c1c2c325b 100644 --- a/doc/windbg.md +++ b/doc/windbg.md @@ -1,23 +1,23 @@ -WinDBG +WinDbg ====== -The WinDBG support for rizin allows you to attach to VM running Windows -using a named socket file (will support more IOs in the future) to -debug a windows box using the KD interface over serial port. +The WinDbg support for Rizin allows you to attach to a VM running Windows +using a named socket file (more IOs will be supported in the future) to +debug a Windows box using the KD interface over a serial port. -Bear in mind that WinDBG support is still work-in-progress, and this is -just an initial implementation which will get better in time. +Bear in mind that WinDbg support is still a work in progress, and this is +just an initial implementation that will get better in time. -It is also possible to use the remote GDB interface to connect and +It is also possible to use the remote GDB interface to connect to and debug Windows kernels without depending on Windows capabilities. -Enable WinDBG support on Windows Vista and higher like this: +Enable WinDbg support on Windows Vista and higher like this: bcdedit /debug on bcdedit /dbgsettings serial debugport:1 baudrate:115200 -Or like this for Windows XP: - Open boot.ini and add /debug /debugport=COM1 /baudrate=115200: +Or, for Windows XP: + Open `boot.ini` and add `/debug /debugport=COM1 /baudrate:115200`: [boot loader] timeout=30 @@ -26,7 +26,7 @@ Or like this for Windows XP: multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Debugging with Cable" /fastdetect /debug /debugport=COM1 /baudrate=57600 -Configure the VirtualBox Machine like this: +Configure the VirtualBox machine like this: Preferences -> Serial Ports -> Port 1 @@ -36,20 +36,20 @@ Configure the VirtualBox Machine like this: [v] Create Pipe Port/File Path: [_/tmp/winkd.pipe____] -Or just spawn the VM with qemu like this: +Or just spawn the VM with QEMU like this: $ qemu-system-x86_64 -chardev socket,id=serial0,\ path=/tmp/winkd.pipe,nowait,server \ -serial chardev:serial0 -hda Windows7-VM.vdi -Rizin will use the 'winkd' io plugin to connect to a socket file -created by virtualbox or qemu. Also, the 'winkd' debugger plugin and -we should specify the x86-32 too. (32 and 64 bit debugging is supported) +Rizin will use the `winkd` IO plugin to connect to a socket file created by +VirtualBox or QEMU. Also, we should specify the `winkd` debugger plugin +and `x86-32`. (32- and 64-bit debugging is supported). $ rizin -a x86 -b 32 -D winkd winkd:///tmp/winkd.pipe -On Windows you should run the following line: +On Windows, you should run the following line: $ rizin -D winkd winkd://\\.\pipe\com_1 @@ -64,16 +64,16 @@ At this point, we will get stuck here: 0x828997be c3 ret 0x828997bf 90 nop -In order to skip that trap we will need to change eip and run 'dc' twice: +In order to skip that trap, we will need to change `eip` and run `dc` twice: dr eip=eip+1 dc dr eip=eip+1 dc -Now the Windows VM will be interactive again. We will need to kill rizin and -attach again to get back to control the kernel. +Now, the Windows VM will be interactive again. We will need to kill Rizin +and attach again to get back control of the kernel. -In addition, the `dp` command can be used to list all processes, and -`dpa` or `dp=` to attach to the process. This will display the base +In addition, the `dp` command can be used to list all processes, and `dpa` +or `dp=` can be used to attach to a process. This will display the base address of the process in the physical memory layout. diff --git a/librz/arch/isa/arm/arm_il32.c b/librz/arch/isa/arm/arm_il32.c index 3c48b568a51..e5079c6bbb2 100644 --- a/librz/arch/isa/arm/arm_il32.c +++ b/librz/arch/isa/arm/arm_il32.c @@ -2663,7 +2663,7 @@ static RzILOpEffect *write_reg_lane(arm_reg reg, ut32 lane, ut32 vec_size, RzILO /** * For Extend Instruction Set - * TODO: Split to a seperate file and include before arm lifter + * TODO: Split to a separate file and include before arm lifter * VFP and NEON */ diff --git a/librz/include/rz_util/rz_annotated_code.h b/librz/include/rz_util/rz_annotated_code.h index 6913642fa44..64f995ba744 100644 --- a/librz/include/rz_util/rz_annotated_code.h +++ b/librz/include/rz_util/rz_annotated_code.h @@ -164,7 +164,7 @@ RZ_API RzPVector /**/ *rz_annotated_code_annotations_range(R /** * @brief Returns the offset for every line of decompiled code in the specified RzAnnotatedCode. * - * Creates an @ref RzVector and inserts the offsets for every seperate line of decompiled code in + * Creates an @ref RzVector and inserts the offsets for every separate line of decompiled code in * the specified RzAnnotatedCode. * If a line of decompiled code doesn't have a unique offset, UT64_MAX is inserted as its offset. * diff --git a/librz/io/io.c b/librz/io/io.c index 6044f02e453..a21abc61d63 100644 --- a/librz/io/io.c +++ b/librz/io/io.c @@ -408,7 +408,7 @@ RZ_API RZ_OWN RzBuffer *rz_io_nread_at_new_buf(RZ_NONNULL RzIO *io, ut64 addr, s * \param buf The buffer to read the data for writing. * \param len The number of bytes to write. * \return true The write was successful. - * \return false The write as unsucessful or \p len was less then 1. + * \return false The write as unsuccessful or \p len was less then 1. */ RZ_API bool rz_io_write_at(RzIO *io, ut64 addr, const ut8 *buf, size_t len) { int i; diff --git a/librz/sign/flirt.c b/librz/sign/flirt.c index d9896a396f4..ab916c383b1 100644 --- a/librz/sign/flirt.c +++ b/librz/sign/flirt.c @@ -1308,7 +1308,7 @@ RZ_API RZ_OWN RzFlirtNode *rz_sign_flirt_parse_compressed_pattern_from_buffer(RZ * * \param analysis The RzAnalysis structure * \param flirt_file The FLIRT file to parse - * \return true if the signatures were sucessfully applied to the file + * \return true if the signatures were successfully applied to the file */ RZ_API bool rz_sign_flirt_apply(RZ_NONNULL RzAnalysis *analysis, RZ_NONNULL const char *flirt_file, ut8 expected_arch) { rz_return_val_if_fail(analysis && RZ_STR_ISNOTEMPTY(flirt_file), false); diff --git a/librz/util/sdb/src/cdb.c b/librz/util/sdb/src/cdb.c index 8523935eeaa..6e322875766 100644 --- a/librz/util/sdb/src/cdb.c +++ b/librz/util/sdb/src/cdb.c @@ -239,7 +239,7 @@ static int match(struct cdb *c, const char *key, ut32 len, ut32 pos) { } /** - * \brief Find the next occurence of \p key in the \ref cdb structure. + * \brief Find the next occurrence of \p key in the \ref cdb structure. * \param u The hash of the \p key to search for. * \param key The key, a NUL-terminated string. * \param len The string length of \p key. diff --git a/subprojects/rzar/ar.c b/subprojects/rzar/ar.c index 451bdc99a69..9a1fcacc0c2 100644 --- a/subprojects/rzar/ar.c +++ b/subprojects/rzar/ar.c @@ -60,7 +60,7 @@ static char *name_from_table(ut64 off, filetable *tbl) { RZ_LOG_ERROR("ar: Malformed ar: name lookup out of bounds for header at offset 0x%" PFMT64x "\n", off); return NULL; } - // files are suppose to be line feed seperated but we also stop on invalid + // files are suppose to be line feed separated but we also stop on invalid // chars, such as '/' or '\0' char *buf = tbl->data; diff --git a/test/unit/test_str.c b/test/unit/test_str.c index d9341db1c9c..98154c97b1c 100644 --- a/test/unit/test_str.c +++ b/test/unit/test_str.c @@ -585,7 +585,7 @@ bool test_rz_str_str_xy(void) { mu_assert_eq(x, 0, "x of fourth occurrence"); mu_assert_eq(y, 2, "y of fourth occurrence"); next = rz_str_str_xy(canvas, "World", next, &x, &y); - mu_assert_null(next, "no more occurences"); + mu_assert_null(next, "no more occurrences"); mu_end; } diff --git a/test/unit/test_strbuf.c b/test/unit/test_strbuf.c index 1e6c01b7a99..754241ed368 100644 --- a/test/unit/test_strbuf.c +++ b/test/unit/test_strbuf.c @@ -151,10 +151,10 @@ bool test_rz_strbuf_setf(void) { bool test_rz_strbuf_initf(void) { RzStrBuf sb; - const char *s = rz_strbuf_initf(&sb, "hmmst, %s was that audial occurence? %d", "wat", 42); + const char *s = rz_strbuf_initf(&sb, "hmmst, %s was that audial occurrence? %d", "wat", 42); mu_assert_notnull(s, "initf return notnull"); mu_assert_ptreq(s, rz_strbuf_get(&sb), "initf return"); - mu_assert_streq(rz_strbuf_get(&sb), "hmmst, wat was that audial occurence? 42", "initf"); + mu_assert_streq(rz_strbuf_get(&sb), "hmmst, wat was that audial occurrence? 42", "initf"); rz_strbuf_fini(&sb); mu_end; }