commands help: what we want

[ret2libc]

With the new parser and work ongoing to improve RCmd so that commands are directly called by it and not with a set of switch/cases everywhere, it's probably a good time to choose what kind of information we want to show for help.

When the refactoring in RCmd will be done, help messages should be printed dynamically by RCmd itself, based on the structure defined during the registration of commands. In a nutshell, commands are organized in a tree of RCmdDesc.

Example:

root
-> a
   -> a
   -> af
      -> af
      -> afr
      -> afl
      [...]
   -> ah
   [...]
-> C
   [...]
-> w
    -> w0
    -> wv8
    [...]
[...]

Let's use this issue to gather ideas about what's needed.

[ret2libc]

For each RCmdDesc I think we need at least:

• summary of the command. Example: afB would have as a summary set current function as thumb (change asm.bits). This summary can be used when printing the help of af?
• args_str. Example: afB would have as args_str [bits]. This args_str can be used when printing the help of af?, to show something like | afB [bits] # summary
• description. This can be a more detailed description of the command that is shown when the help of the particular command is requested.
• examples. This can be a list of examples on how to use the command, similar to what's provided in pf???.

[karliss]

• Nontrivial argument description. afll? pf?? ag? wA . This more or less belong to description unless it's very long.
• Legend/command output description pxA?. Part of description unless very long.

[ret2libc]

[0x00000000]> p?
Usage: p[=68abcdDfiImrstuxz] [arg|len] [@addr]  
| p[b|B|xb] [len] ([S])   bindump N bits skipping S bytes
| p[iI][df] [len]         print N ops/bytes (f=func) (see pi? and pdi)
| p[kK] [len]             print key in randomart (K is for mosaic)
| p-[?][jh] [mode]        bar|json|histogram blocks (mode: e?search.in)
| p2 [len]                8x8 2bpp-tiles
...

Is it really useful to have the first line Usage: p[=68abcdDfiImrstuxz] [arg|len] [@addr]? Do we want to keep it? I'm not sure about that, since anyway all the information are already in the list of commands and the arguments can be really different between different commands, so you should really see the specific command if you want to know more about the arguments of a command.

Opinions @karliss @radare ?

[radare]

The oneliner help can become useless when there are lot of subcommands.. maybe we can set a limit and just add ... if doesnt fit, for short ones i think its fine at least it makes my eye read it faster but its also fine and simpler to just skip them and describe them below

On 7 May 2020, at 15:43, Riccardo Schirone notifications@github.com wrote:

 [0x00000000]> p? Usage: p[=68abcdDfiImrstuxz] [arg|len] [@addr]
| p[b|B|xb] [len] ([S]) bindump N bits skipping S bytes | p[iI][df] [len] print N ops/bytes (f=func) (see pi? and pdi) | p[kK] [len] print key in randomart (K is for mosaic) | p-[?][jh] [mode] bar|json|histogram blocks (mode: e?search.in) | p2 [len] 8x8 2bpp-tiles ... Is it really useful to have the first line Usage: p[=68abcdDfiImrstuxz] [arg|len] [@addr]? Do we want to keep it? I'm not sure about that, since anyway all the information are already in the list of commands and the arguments can be really different between different commands, so you should really see the specific command if you want to know more about the arguments of a command.

Opinions @karliss @radare ?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[ret2libc]

@karliss @trufae how do we handle things like pf? Right now there are 3 helps for pf: pf? (regular help), pf?? (format descriptions) and pf??? (examples). As things are structured right now in the new help, format descriptions and examples would go together. Does it make sense? What do you think? Shall we keep them separate?

[trufae]

Yes i think it makes sense to be consistent on that. also if there's any extended help it should be shown in the root help message.

but this is contradictory/conflicting with the usage of ? and ?? in the root (? = help, ?? = conditional, ??? = help of the help command).

[ret2libc]

Yes i think it makes sense to be consistent on that. also if there's any extended help it should be shown in the root help message.

For consistency with all the other commands, would it make sense to swap the two? So pf?? is long description + examples (as I have done for all the other commands) and pf??? is for formats and additional free-text help.

but this is contradictory/conflicting with the usage of ? and ?? in the root (? = help, ?? = conditional, ??? = help of the help command).

Good point. I guess I can special-case the root, if necessary.

[ret2libc]

Another question I have is: how do we want the recursive help to look like?

Right now:

[0x00000000]> w?*
Usage: w[x] [str] [<file] [<<EOF] [@addr]  
| w[1248][+-][n]       increment/decrement byte,word..
| w foobar             write string 'foobar'
| w0 [len]             write 'len' bytes with value 0x00
| w6[de] base64/hex    write base64 [d]ecoded or [e]ncoded string
| wa[?] push ebp       write opcode, separated by ';' (use '"' around the command)
| wc                   list all write changes
| we[?] [nNsxX] [arg]  extend write operations (insert instead of replace)
| wh r2                whereis/which shell command
| wo[?] hex            write in block with operation. 'wo?' fmi
| wp[?] -|file         apply radare patch file. See wp? fmi
| wr 10                write 10 random bytes
| ws pstring           write 1 byte for length and then the string
| wt[f][?] file [sz]   write to file (from current seek, blocksize or sz bytes)
| wv[?] eip+34         write 32-64 bit value honoring cfg.bigendian
| wz string            write zero terminated string (like w + \x00)
Usage: wa[of*] [arg]  
| wa nop           write nopcode using asm.arch and asm.bits
| wai jmp 0x8080   write inside this op (fill with nops or error if doesnt fit)
| wa* mov eax, 33  show 'wx' op with hexpair bytes of assembled opcode
| "wa nop;nop"     assemble more than one instruction (note the quotes)
| waf f.asm        assemble file and write bytes
| waF f.asm        assemble file and write bytes and show 'wx' op with hexpair bytes of assembled code
| waF* f.asm       assemble file and show 'wx' op with hexpair bytes of assembled code
| wao?             show help for assembler operation on current opcode (hack)
Usage: wc[jir+-*?]    # NOTE: Uses io.cache=true
| wc               list all write changes
| wcj              list all write changes in JSON
| wc- [from] [to]  remove write op at curseek or given addr
| wc+ [from] [to]  commit change from cache to io
| wc*              "" in radare commands
| wcr              reset all write changes in cache
| wci              commit write cache
| wcp [fd]         list all cached write-operations on p-layer for specified fd or current fd
| wcp* [fd]        list all cached write-operations on p-layer in radare commands
| wcpi [fd]        commit and invalidate pcache for specified fd or current fd
| Usage                            write extend # resize the file
| wen <num>                        extend the underlying file inserting NUM null bytes at current offset
| weN <addr> <len>                 extend current file and insert bytes at address
| wes <addr>  <dist> <block_size>  shift a blocksize left or write in the editor
| wex <hex_bytes>                  insert bytes at current offset by extending the file
| weX <addr> <hex_bytes>           insert bytes at address by extending the file
...

I think this is not really "recursive" and it looks a bit confusing to read, because you have all the direct sub-commands of w, then wa and all its subcommands, then wb and all its subcommands. All interleaved with a "Usage:" message that doesn't really say anything new that wasn't already said. What do you think about something like:

[0x00000000]> w?*
Usage: w[x] [str] [<file] [<<EOF] [@addr]  
| w foobar             write string 'foobar'
| w0 [len]             write 'len' bytes with value 0x00
| w6[de] base64/hex    write base64 [d]ecoded or [e]ncoded string
| wa[?] push ebp       write opcode, separated by ';' (use '"' around the command)
| wa nop           write nopcode using asm.arch and asm.bits
| wai jmp 0x8080   write inside this op (fill with nops or error if doesnt fit)
| wa* mov eax, 33  show 'wx' op with hexpair bytes of assembled opcode
| "wa nop;nop"     assemble more than one instruction (note the quotes)
| waf f.asm        assemble file and write bytes
| waF f.asm        assemble file and write bytes and show 'wx' op with hexpair bytes of assembled code
| waF* f.asm       assemble file and show 'wx' op with hexpair bytes of assembled code
| wao?             show help for assembler operation on current opcode (hack)
| wc                   list all write changes
| wcj              list all write changes in JSON
| wc- [from] [to]  remove write op at curseek or given addr
| wc+ [from] [to]  commit change from cache to io
| wc*              "" in radare commands
| wcr              reset all write changes in cache
| wci              commit write cache
| wcp [fd]         list all cached write-operations on p-layer for specified fd or current fd
| wcp* [fd]        list all cached write-operations on p-layer in radare commands
| wcpi [fd]        commit and invalidate pcache for specified fd or current fd
| we[?] [nNsxX] [arg]  extend write operations (insert instead of replace)
| wh r2                whereis/which shell command
| wo[?] hex            write in block with operation. 'wo?' fmi
| wo[24aAdlmorwx]               without hexpair values, clipboard is used
| wo2 [val]                     2=  2 byte endian swap (word)
| wo4 [val]                     4=  4 byte endian swap (dword)
| wo8 [val]                     8=  8 byte endian swap (qword)
| woa [val]                     +=  addition (f.ex: woa 0102)
| woA [val]                     &=  and
| wod [val]                     /=  divide
| woD[algo] [key] [IV]          decrypt current block with given algo and key
| woe [from to] [step] [wsz=1]  ..  create sequence
| woE [algo] [key] [IV]         encrypt current block with given algo and key
| wol [val]                     <<= shift left
| wom [val]                     *=  multiply
| woo [val]                     |=  or
| wop[DO] [arg]                 De Bruijn Patterns
| wor [val]                     >>= shift right
| woR                           random bytes (alias for 'wr $b')
| wos [val]                     -=  substraction
| wow [val]                     ==  write looped value (alias for 'wb')
| wox [val]                     ^=  xor  (f.ex: wox 0x90)
| wp[?] -|file         apply radare patch file. See wp? fmi
| wr 10                write 10 random bytes
| ws pstring           write 1 byte for length and then the string
| wt[f][?] file [sz]   write to file (from current seek, blocksize or sz bytes)
| wv[?] eip+34         write 32-64 bit value honoring cfg.bigendian
| wz string            write zero terminated string (like w + \x00)

? The difference in this second output is that for each direct child in the tree, I immediately visit the children and print their helps.

[wargio]

i actually prefer the 1st one, but the 2nd one is more r2 like.

[karliss]

I already mentioned the idea in poll. Instead of having [?] submenu availability could be indicated by changing |.

Usage: w[x] [str] [<file] [<<EOF] [@addr]  
| w[1248][+-][n]       increment/decrement byte,word..
| w foobar             write string 'foobar'
| w0 [len]             write 'len' bytes with value 0x00
| w6[de] base64/hex    write base64 [d]ecoded or [e]ncoded string
+ wa push ebp          write opcode, separated by ';' (use '"' around the command)
+ wc                   list all write changes
+ we [nNsxX] [arg]     extend write operations (insert instead of replace)
| wh r2                whereis/which shell command
+ wo hex               write in block with operation. 'wo?' fmi
+ wp -|file            apply radare patch file. See wp? fmi
| wr 10                write 10 random bytes
| ws pstring           write 1 byte for length and then the string
+ wt[f] file [sz]      write to file (from current seek, blocksize or sz bytes)
+ wv eip+34            write 32-64 bit value honoring cfg.bigendian
| wz string            write zero terminated string (like w + \x00)

[ret2libc]

[XVilka]

@ret2libc isn't this already implemented so we can close this?

[ret2libc]

Yes I think we can close this and open new issues as necessary.