Session¶

Add a comment that ends at the next ; ($$) or at the end of the line (*).

$$ [text]

Also: *

$<¶

Run the commands in a script file on the machine that ntoseye runs on.

$< <filename> [argument]...

Also: $><, $$<, $$><, $$>a<

$< and $$< run the file one line at a time, while $><, $$><, and $$>a< join its lines with ; into one command block. Use these forms if the .if or .while blocks of a script span lines. $< and $>< use the rest of the line as the file name, ; included. For the $$ forms, the file name ends at ;, so other commands can follow. $$>a< accepts a quoted file name if the name has spaces, and replaces ${$arg1}…${$argN} in the file with its arguments as written. If argument N is not given, ${$argN} stays as written. $$>a< replaces ${/d:$argN} with 1 if argument N is given, else with 0. $$>a< shows only the output of the commands, and the other forms show each command before it runs. Scripts can run scripts, up to a depth of 16. Ctrl+C stops a script between commands.

.block¶

Run a block of commands.

.block { <commands> }

WinDbg uses a block to evaluate its ${alias} aliases again. Because ntoseye expands aliases when each command runs, a block in ntoseye only groups commands.

.break¶

Stop the innermost .for, .while, or .do loop.

.break

As in WinDbg, .break does not stop .foreach and !for_each_* loops. Usually, you put .break in an .if block. For example: .while (1) { r $t0 = @$t0 + 1; .if (@$t0 > 5) { .break } }.

.cls¶

Clear the terminal screen if stdout is a terminal.

.cls

.continue¶

Start the next pass of the innermost .for, .while, or .do loop.

.continue

.do¶

Run a block of commands, then run it again while a condition is true.

.do { <commands> } (<condition>)

Condition is an expression that the loop evaluates after each pass, and a nonzero value is true. .break stops the loop, and .continue goes to the condition. Ctrl+C, or a timeout or cancellation of a remote call, stops the loop between passes.

.echo¶

Print text without evaluating expressions in it.

.echo [text]

Also: echo

.echotime¶

Print the current date and time of the host in UTC.

.echotime

.else¶

Run a block when no condition of an .if statement is true.

.else { <commands> }

Use this only immediately after an .if or .elsif block. See .if.

.elsif¶

Add a condition to an .if statement.

.elsif (<condition>) { <commands> }

Use this only immediately after an .if or .elsif block. See .if.

.for¶

Run a block of commands in a loop, like the C for statement.

.for (<initial-command> ; <condition> ; <increment-command>) { <commands> }

InitialCommand runs once. Then, while the expression Condition is nonzero, the block runs, followed by IncrementCommand. Usually, the two commands are pseudo-register assignments, for example: .for (r $t0 = 0; @$t0 < 4; r $t0 = @$t0 + 1) { ? @$t0 }. .break stops the loop, and .continue goes to IncrementCommand. Ctrl+C, or a timeout or cancellation of a remote call, stops the loop between passes.

.foreach¶

Run commands once for each token of a command’s output, a string, or a file.

.foreach [/pS <count>] [/ps <count>] (<variable> { <in-commands> }) { <out-commands> }
.foreach [/pS <count>] [/ps <count>] /s (<variable> "<in-string>") { <out-commands> }
.foreach [/pS <count>] [/ps <count>] /f (<variable> "<in-file>") { <out-commands> }

InCommands run first, with their output hidden. ntoseye shows their errors and warnings and does not use them as tokens. It splits the output (or InString, or the text of InFile) into tokens at spaces, tabs, and line breaks, and then runs OutCommands once for each token. In each run, the token replaces each whole-word occurrence of Variable, which must stand alone between spaces, or at the start or end of OutCommands. The token replaces ${Variable} anywhere, also inside other text. If a token contains ; or a quote, ntoseye inserts it as a quoted string, so the token cannot end its command and start a new one. /pS n skips the first n tokens, and /ps n skips n tokens after each token that the loop uses. For example, .foreach /pS 2 /ps 4 uses the 3rd, 8th, 13th token, and so on. The skip counts are expressions in the current radix. OutCommands can contain several commands separated by ;, another .foreach, or !for_each_*. Ctrl+C stops the loop. If the session does not permit a command (for example, a resume in a breakpoint action), the loop stops and the rest of the command line does not run. If a command only shows an error, the loop continues.

.hh¶

List commands or show detailed help for one command.

.hh [command]

Also: help, .help

.if¶

Run a block of commands if a condition is true, like the C if statement.

.if (<condition>) { <commands> } [.elsif (<condition>) { <commands> }]... [.else { <commands> }]

Each Condition is an expression, and a nonzero value is true. The block of the first true condition runs, and if no condition is true, the .else block runs, if there is one. Spaces and line breaks can separate the parts, and so can the ; that $$>< puts at each line break of a script. Commands after the statement run after the statement ends, for example: .if (@rcx == 0) { .echo null } .else { dq @rcx L1 }; k.

.logappend¶

Start a debugger transcript and append it to the file.

.logappend <file>

.logclose¶

Close the debugger transcript.

.logclose

.logopen¶

Start a debugger transcript and replace any existing file.

.logopen <file>

.printf¶

Format debugger values with WinDbg-style printf specifiers.

.printf "<format>" [, <argument>]...

Put the arguments after the format and separate them with commas, as in WinDbg (.printf "%p %d\n", poi(@rcx + 8), @$t0). If each argument is one word, you can separate them with spaces.

.shell¶

Run a host command, and optionally send debugger output to it.

.shell [-ci "<debugger-commands>"] <host-command>

The command runs with the shell of the host (sh -c) and waits until it exits. It shows what the host command writes to standard output and standard error, and then the exit status if the status is not zero. With -ci, the quoted debugger commands (separated by ;) run first, and their output becomes the standard input of the host command. For example, .shell -ci "lm" grep nt filters the module list, and .shell -ci "!process 0 0" sort sorts the process list. ntoseye shows errors from the debugger commands and does not send them to the host command. Without -ci, the host command reads an empty standard input. The rest of the line, ; included, is the host command. Only the interactive prompt can run .shell. ntoseye does not permit it in a line from MCP, DAP, the Python SDK, a GDB client monitor command, a breakpoint action, or an exception command, because none of these may start host programs.

.sleep¶

Pause the debugger for a number of milliseconds.

.sleep <milliseconds>

Milliseconds is an expression in the current radix (.sleep 0n500). Ctrl+C, or a timeout or cancellation of a remote call, ends the pause early. The command does not change the target, so a running target continues to run.

.while¶

Run a block of commands while a condition is true.

.while (<condition>) { <commands> }

Condition is an expression that the loop evaluates before each pass, and a nonzero value is true. .break stops the loop, and .continue starts the next pass. Ctrl+C, or a timeout or cancellation of a remote call, stops the loop between passes. If the session does not permit a command, the loop stops and the rest of the command line does not run.

ad¶

Remove a command alias.

ad <name>

Also: unalias

al¶

List command aliases.

al

Also: aliases

as¶

Define a command alias.

as <name> <expansion>

Also: alias

j¶

Run one of two commands, based on the value of an expression.

j <expression> <command1> [; <command2>]
j <expression> '<commands1>' [; '<commands2>']

If Expression is nonzero, Command1 runs, and otherwise Command2 runs. To put several commands in a branch, separate them with ; and put them in single quotes. Each branch can be empty ('', or nothing before the ;). j uses the rest of the line, so it ignores text after Command2. In a breakpoint action, a gc in either branch resumes the target. For example: bp nt!NtClose "j (@rcx == 0) '.echo null handle' ; 'gc'".

q¶

Exit, remove the breakpoints of this session, and leave the guest running.

Also: quit, qd

This is the WinDbg qd command (quit and detach), and ntoseye also accepts qd. If this session halted the guest, q resumes it. If q cannot remove a breakpoint from the guest, it leaves the guest halted, because if q resumed that guest, the breakpoint could trap when there is no debugger.

reload-scripts¶

Reload custom commands and aliases.

reload-scripts