Special Command—Advanced Programming Techniques for WinDbg Scripts


It has been a long time since my last post, but I’m back on the blog.


The article for today is about the black art of WinDbg scripting. When I first started creating my scripts, I learned by trial and error. It was tough; however, it gave me the basis to create the technique that has proven to be useful when creating scripts.


If you’ve been following my blog, you should know the PowerDbg tool. PowerDbg is another approach to create scripts for WinDbg; however, it’s more useful when creating large and complex scripts. By the way, the next version is going to use a COM object; thus it’s going to be easier to use, more powerful, and faster.


The purpose of this article is to explain the most used commands and the techniques I use to create scripts.


 


1-   Declaring Variables


 


Variables are created as aliases not as real variables. I’m going to use the term “variable”, but in fact we’re talking about aliases.


Aliases are very flexible. You can, for instance, create an alias that has a block of commands.


Here is the way to create and delete variables:


 


as [alias type] <alias Name> <value>


 


Where [alias type] can be:


 


/ma             Sets the alias equivalent equal to the null-terminated ASCII string that begins at Address.


/mu             Sets the alias equivalent equal to the null-terminated Unicode string that begins at Address.


/msa              Sets the alias equivalent equal to the ANSI_STRING structure that is located at Address.


/msu              Sets the alias equivalent equal to the UNICODE_STRING that is structure located at Address.


Address         Specifies the location of the virtual memory that is used to determine the alias equivalent.


/x                    Sets the alias equivalent equal to the 64-bit value of Expression.


Expression     Specifies the expression to evaluate. This value becomes the alias equivalent.


/f                    Sets the alias equivalent equal to the contents of the File file. You should always use the /f switch together with aS, not with as.


File              Specifies the file whose contents become the alias equivalent. File can contain spaces, but you should never enclose File in quotation marks. If you specify an invalid file, you receive an “Out of memory” error message.


/c                    Sets the alias equivalent equal to the output of the commands that CommandString specify. The alias equivalent includes carriage returns if they are present within the command display and a carriage return at the end of the display of each command (even if you specify only one command).


Example:


 


as ${/v:ScriptName} myscripts\\test_script.txt


 


The example above creates an alias ScriptName that represents the path described above.


Notice that I’m using ${/v:}


Why is that?


If you don’t use ${/v:}, you’ll have problems to delete the alias. You can see in some of my old scripts I used this approach, so if you call the script two times in a row an error occurs because the alias couldn’t be deleted!


 


${} is an alias interpreter.


 


The options are:


 


/d                Evaluates to one or zero depending on whether the alias is currently defined. If the alias is defined, ${/v:Alias} is replaced by 1; if the alias is not defined, ${/v:Alias} is replaced by 0.


 


/f                    Evaluates to the alias equivalent if the alias is currently defined. If the alias is defined, ${/f:Alias} is replaced by the alias equivalent; if the alias is not defined, ${/f:Alias} is replaced by an empty string.


 


/n                    Evaluates to the alias name if the alias is currently defined. If the alias is defined, ${/n:Alias} is replaced by the alias name; if the alias is not defined, ${/n:Alias} is not replaced but retains its literal value of ${/n:Alias}.


 


/v                    Prevents any alias evaluation. Regardless of whether Alias is defined, ${/v:Alias} always retains its literal value of ${/v:Alias}.


 


To simplify follow this template when creating “variables”:


 


as [alias type] ${/v:<alias name>} <alias value>


 


 


 


 


2-   Freeing Variables (aliases)


 


The way to delete “variables” is:


 


ad ${/v:<variable name>}


 


Example:


 


as ${/v:ScriptName} myscripts\\test_script.txt    (creating alias)


 


ad ${/v:ScriptName}  (deleting)


 


So, this is the template:


 


ad ${/v:<variable name>}


 


 


 


3-   Executing Scripts


 


The most common way to call a script is:


 


$$><path\scriptName


 


Example:


 


$$><myscripts\GET_PERFMON.txt


 


If your script accepts arguments you must provide them using:


 


$$>a<path\scriptName argument1 argument2 argument3…


 


Example:


 


$$>a<myscripts\GET_HEADERS.txt kernel32


 


You can use recursive calls and make a script call itself. No secrets here, it’s the exact same command.


 


 


4-   Identifying Arguments


 


If your script accepts arguments, you should verify if the user provided the arguments.


To do that you can test whether the argument was or wasn’t provided, like:


 


.if(${/d:$arg1})


{


    $$ Do something…


}


 


From above you can see the ${/d:} that evaluates the expression to one or zero.


arg1 refers to the first argument, arg2 to the second, and so on.


 


 


 


5-   32/64 bits Compatibility


 


When writing WinDbg scripts, you’ve got to think about 32 and 64 bits compatibility. Most of the time you don’t need to write two scripts to keep compatibility.


The technique is based on this pseudo-register:


 







$ptrsize


The size of a pointer.


 


Example (snippet from a real script):


 


r @$t1 = poi(@$t0) + @$ptrsize;


 


.printf “\n.NET GC Counters\n\n”;


.printf “GenCollection 0           = 0n%d\n”, poi(@$t1);


.printf “GenCollection 1           = 0n%d\n”, poi(@$t1+@$ptrsize);


.printf “GenCollection 2           = 0n%d\n”, poi(@$t1+@$ptrsize*2);


.printf “PromotedMemory            = 0n%d\n”, poi(@$t1+@$ptrsize*3);


.printf “PromotedMemory 1          = 0n%d\n”, poi(@$t1+@$ptrsize*4);


 


Or yet:


 


!do poi(${obj}+(4*@$ptrsize))


 


 


6-   DML – Debug Markup Language


 


If you’ve been following my blog, you know I’m a big DML fan. With DML you can create hyperlinks that execute commands instead of presenting lots of information to the user.


 


To use DML you’ve got to use a variation of the .printf command:


 


.printf /D


 


Note: If you want to learn more about DML, open the DML.DOC that comes with the Debugger.


 


Common usage:


.printf /D <link cmd=\”dps @$csp poi(@$teb+0x4);ad ${/v:ScriptName}; $$><${ScriptName}\”><b>Symbols</b></link>\n\n”


 


From above:


 


<link cmd=\”Your Command Here \”>


 


I’m using \” instead of because I’m using them within a pair of .


 


<b>Your string</b></link>


 


The <b> is to use Bold.


 


Tip: Between <link cmd=\”    \”</link> you could use an alias defined before the DML line. This alias could be a block of code, like:


 


.block


{


    $$ Creating an alias for a block of code!


    as ${/v:OracleCommand} .block


    {


        !DumpObj poi(@$t0+0x14)


        !DumpObj @$t0


        !GCRoot @$t0


    }


}


 


.foreach(obj {!dumpheap -short -type System.Data.OracleClient.OracleCommand } )


{


    .printf /D “<link cmd=\”r @$t0 = ${obj}; ${OracleCommand} ;\”><b>%mu</b></link>\n\n”, poi(${obj}+0x14)+0xc


}


 


.printf is very similar to the printf() function from C programming language.


 


 


7-   Pseudo-Registers as Variables


 


Most of the time, you’ll want to use some kind of counter in your script, or save the address of an object, a structure field, etc. To do that you can use pseudo-registers.


 


I talked about it before, so you can read the full article here.


 


 


8-   Legibility May Hurt Your Script


 


I know it’s weird, but it’s the truth.


If you have a command line like:


 


!do poi(@$t0+(4*@$ptrsize))


 


And you decide to improve the legibility adding a few spaces you may end up having an error.


In other words, this line won’t run:


 


!do poi(@$t0 + (4 * @$ptrsize))


 


It’ll fail with this error:


 


Incorrect argument: + (4 * @$ptrsize))


 


The next article has a script as an example of some of the techniques presented above.


 


The possibilities are limited only by your creativity. If you have a cool script and want to show it to the world feel free to post it in this blog.

Comments (5)

  1. Norman Hamer says:

    Some additional notes on aliases in scripts:

    (1) aS is often better than as in scripts

    as includes all text to the end of the line as the alias. Since $$>a< scripts turn the entire script into a single line, you have to use .block around each alias:

    <<begin script>>

    as ${/v:myalias} kb; dv

    .echo "Alias defined"

    <<end script>>

    will define myalias as kb; dv; .echo "Alias defined"

    The workaround for this is to enclose each alias definition in a block (Roberto uses this technique extensively, but hasn’t called it out):

    <<begin script>>

    .block {

       as ${/v:myalias} kb; dv

    }

    .echo "Alias defined"

    <<end script>>

    However, aS only includes text up to the next unquoted semicolon, so you can use it bare:

    <<begin script>>

    aS ${/v:myalias} "kb; dv"

    .echo "Alias defined"

    <<end script>>

    defines myalias as kb; dv and then echoes "Alias defined"

    (2) ad /q ${/v:aliasname} is your friend

    If an alias isn’t defined, ad ${/v:aliasname} will cause an error and abort your script. ad /q will simply ignore it if not defined

    (3) You need to use .block to force alias evaluation

    Aliases aren’t evaluated until the next block (including blocks started with .if, etc), so the following script will error out at the .echo:

    <<begin script>>

    aS ${/v:myalias} foo

    .echo ${myalias}

    ad /q ${/v:myalias}

    <<end script>>

    If you force evaluation with a block, it will work correctly:

    <<begin script>>

    aS ${/v:myalias} foo

    .block {

       .echo ${myalias}

    }

    ad /q ${/v:myalias}

    <<end script>>

    (4) There’s a bug in the alias interpreter

    The following script should be equivalent to the one above, echoing "foo" to the debugger window:

    <<begin script>>

    aS ${/v:myalias} foo

    .block {

       .if(0 != ${/d:myalias}) {

           .echo ${/f:myalias}

       }

    }

    ad /q ${/v:myalias}

    <<end script>>

    But, unfortunately, it’s not. Even thought ${myalias} evaluates to foo, ${/d:myalias} evaluates to 0. This affects /f: /d: and /n: evaluations

    There’s a workaround, because a command line (and remember, a script is a single line) which begins with an alias command does not do alias evaluation. Just have the first line in the script delete a non-existant alias (this has to be before any comments, whitespace, or whatnot):

    <<begin script>>

    ad /q ${/v:workaround_alias_bug}

    aS ${/v:myalias} foo

    .block {

       .if(0 != ${/d:myalias}) {

           .echo ${/f:myalias}

       }

    }

    ad /q ${/v:myalias}

    <<end script>>

    … works correctly

    (4) The workaround causes some interesting behavior

    … unfortunately for $$>a< scripts, this also means ${$argx} (and probably the rest of the pseudo-aliases) aren’t evaluated if your first command is an alias command. The following script produces a syntax error

    <<begin script>>

    ad /q ${/v:workaround_alias_bug}

    .if(0 != ${/d:$arg1}) {

    .echo ${arg1}

    }

    <<end script>>

    However, you can force evaluation by using .block:

    <<begin script>>

    ad /q ${/v:workaround_alias_bug}

    .block {

       .if(0 != ${/d:$arg1}) {

           .echo ${arg1}

       }

    }

    <<end script>>

    (5) Why I was trying to do that in the first place (aS /e):

    My environment has a lot of debuggers connected to lab machines, which I remote into, and I can’t realistically keep a local script directory up to date, or modify the script for the local machine’s "scripts directory". However, I can set an environment variable on the debugger machine. I think the technique is also probably useful for scripts which might want to use a local user’s preference for editor/diff utility, etc. aS /e copies the value of an OS environment variable to an alias

    <<begin the script which should have worked>>

    aS /e ${/v:script_path} "WINDBG_SCRIPT_PATH"

    .block {

       aS ${/v:run_my_script} $$>a< ${script_path}\myscript.txt

    }

    ad /q ${/v:script_path}

    <<end the script which didn’t work>>

    Unfortunately, aS /e causes an error if the environment variable isn’t defined. .catch to the rescue!

    <<begin script>>

    .catch {

       aS /e ${/v:script_path} "WINDBG_SCRIPT_PATH"

    }

    .block {

       .if(0 != ${/d:script_path}) { $$ May not be defined if there was an error

           aS ${/v:run_my_script} ${script_path}\myscript.txt

       }

       .else {

           .echo "WINDBG_SCRIPT_PATH not defined"

       }

    }

    ad /q ${/v:script_path}

    <<end script>>

    But, of course, this doesn’t work either, because of the alias interpreter bug

    So, with the workaround (and one neat little trick), it looks like this:

    <<begin working script>>

    ad /q ${/v:workaround_alias_bug}

    .catch {

       $$ Use the .foreach to eat any possible output if the environment variable wasn’t defined

       .foreach (v {aS /e ${/v:script_path} "WINDBG_SCRIPT_PATH"}) {}

    }

    .block {

       .if(0 != ${/d:script_path}) { $$ May not be defined if there was an error

           aS ${/v:run_my_script} ${script_path}\myscript.txt

       }

       .else {

           .echo "WINDBG_SCRIPT_PATH not defined"

       }

    }

    ad /q ${/v:script_path}

    <<end working script>>

  2. Hi Norman,

    Great technique!

    I appreciate the time you spent to write and share such a detailed explanation!

    Roberto

  3. Jack says:

    Hi Roberto,

    When I use "as" in a chain command like

    as /c ${/v:mcs} kc1; k;

    last k command was also included in the mcs string output.. but if I run each command sperately It works. What is the right way to use "as" in a command chain? It should only consider kc1

    Thanks!

  4. Hi Jack,

    When using “as /c” the commands are separated by semicolon so in your case your alias is going to execute “kc1;k”.

    If you want to associate just the first command you should use:

    .block{as /c ${/v:mcs} kc1}; k;

    After doing that the “k” command is going to be executed, however, the “kc1” command will only execute if you use:

    .echo ${mcs}

    Thanks,

    Roberto