From 394b6ca8d15498c838cac8abc84706228f12396c Mon Sep 17 00:00:00 2001 From: itayc0hen Date: Sat, 21 Mar 2020 15:30:23 +0200 Subject: [PATCH] Update docs for cmdRaw and cmdRawAt --- docs/source/developers-docs.rst | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/source/developers-docs.rst b/docs/source/developers-docs.rst index 85340e05..817aef0a 100644 --- a/docs/source/developers-docs.rst +++ b/docs/source/developers-docs.rst @@ -29,10 +29,20 @@ Example: Calling a radare2 command ~~~~~~~~~~~~~~~~~~~~~~~~~ -There are two ways to call a radare2 command: +There are multiple ways to call a radare2 command: -- ``CutterCore::cmd()`` *(Discouraged)* Only use it for commands which yells no output -- ``CutterCore::cmdj()`` To be used with json commands like ``cmdj("agj")`` or ``cmdj("aflj")``. +- ``CutterCore::cmdj()`` - To be used with json commands like ``cmdj("agj")`` or ``cmdj("aflj")``. + This is the command we used to fetch structured data from radare2. + +- ``CutterCore::cmdRaw()`` - Executes a single radare2 command + without going through radare2 shell functionality like output redirects, grep, and multiple command parsing. +The command then returns its output. This should be used when a command doesn't have output or the output should be handled as-is. If possible, using the json variation with ``cmdj`` is always preferred. + +- ``CutterCore::cmdRawAt(,
)`` - Executes a single radare2 command in a given address and returns the output. This helps avoiding weird strings concatenation like ``cmd("ph " + hash + " @ " + QString::num(address))``. + +- ``CutterCore::cmd()`` - *(Discouraged)* Only use it when ``cmdj`` or ``cmdRaw`` cannot be used. This is used for complex commands using concatenation of several commands (``px 5; pd 7; afl;``), for grepping (``pd 5~call``). for commands inside commands (``?e `afn.```) and so on. + This is also used when the output is complex and does not parsed correctly in ``cmdRaw``. + Make sure to carefully sanitize user-controlled variables that are passed to the command, to avoid unexpected command injections. Generally, if one needs to retrieve information from a radare2 command, it is preferred to use the json API. @@ -57,6 +67,11 @@ Example: Core()->seek(0x00C0FFEE); +.. note:: + + Cutter also supports a silent seek which doesn't trigger the ``seekChanged`` event and doesn't add new entries to the seek history. + + Creating a widget ~~~~~~~~~~~~~~~~~