NtTrace - Native API tracing for Windows

NtTrace provides a simple trace facility for the Windows Native API. It is roughly equivalent to strace on Linux.
The native API is the interface between the application space and the OS kernel; this API is provided by ntdll.dll. It is not very well documented, and changes between versions of Windows, but tracing execution of an application at this level can provide a clear view of its use of the operating system.

NtTrace uses the debugging interface on Windows to intercept the returns from the native API and display the input arguments and return code. Return codes are translated to Window error code and error messages where possible.
(Click here for some links to other similar tools.)

Example: 

C:> NtTrace -filter File cmd
Process 2428 starting at 4AD0B814 with command line "cmd"
Loaded DLL at 77F40000 ntdll.dll
NtOpenFile(FileHandle=0x12fb38 [0x14], DesiredAccess=SYNCHRONIZE|0x20, ObjectAttributes="\??\C:\WWW\NtTrace\", IoStatusBlock=0x0012FAE4 [0/1], ShareAccess=3, OpenOptions=0x21) => 0
NtQueryVolumeInformationFile(FileHandle=0x14, IoStatusBlock=0x0012FAE4 [0/8], FsInformation=0x12faf4, Length=8, FsInformationClass=4 [FileFsDeviceInformation]) => 0
NtFsControlFile(FileHandle=0x14, Event=0, UserApcRoutine=null, UserApcContext=null, UserIoStatus=0x0012F754 [0/0], FsControlCode=0x00090028, InputBuffer=null, InputBufferLength=0, OutputBuffer=null, OutputBufferLength=0) => 0
NtQueryAttributesFile(ObjectAttributes="\??\C:\WINDOWS\system32\cmd.exe.Local", Attributes=0x0012FADC [0]) => 0xc0000034
 [2 'The system cannot find the file specified.']

...

NtWriteFile(FileHandle=4, Event=0, ApcRoutine=null, ApcContext=null, IoStatusBlock=0x0012FD8C [0/0x29], Buffer=0x4ad30e40, Length=0x29, ByteOffset=null, Key=null) => 0
NtQueryVolumeInformationFile(FileHandle=4, IoStatusBlock=0x0012FB80 [0/8], FsInformation=0x12fb88, Length=8, FsInformationClass=4 [FileFsDeviceInformation]) => 0
NtWriteFile(FileHandle=4, Event=0, ApcRoutine=null, ApcContext=null, IoStatusBlock=0x0012FB48 [0/2], Buffer=0x4ad30e40, Length=2, ByteOffset=null, Key=null) => 0
NtQueryVolumeInformationFile(FileHandle=4, IoStatusBlock=0x0012FB84 [0/8], FsInformation=0x12fb8c, Length=8, FsInformationClass=4 [FileFsDeviceInformation]) => 0
C:\WWW\NtTrace>NtWriteFile(FileHandle=4, Event=0, ApcRoutine=null, ApcContext=null, IoStatusBlock=0x0012FB4C [0/0xf], Buffer=0x4ad30e40, Length=0xf, ByteOffset=null, Key=null) => 0
Process 2428 exit code: 0
Syntax:
  nttrace [-a] [-e] [-v] [-config *] [-errors *] [-export *] [-filter *] [-category *] [-hd] [-nonames] [-nodlls] [-noexcept] [-out *] [-pre] [-stack] [-time] [-delta] [-pid] [-tid] [-nl] [pid | cmd ]

Options:

-a attach to existing process <cmd> rather than starting a fresh <cmd>
-e Only log errors
-v More verbose logging
-config Specify config file
-errors Comma delimited list of error codes to filter on
-export Export symbols once loaded [for testing]
-filter Comma delimited list of substrings to filter on
-category Comma delimited list of categories to trace (eg File,Process,Registry, ? for list) *
-hd Don't use debug heap
-nonames Don't name arguments
-nodlls Don't process DLL load/unload
-noexcept Don't process exceptions
-out Output file
-pre Trace pre-call as well as post-call
-stack show stack trace
-time show timestamp
-delta show delta time
-pid show process ID
-nl force newline on OutputDebugString

* the full list of categories is soft-configured from NtTrace.cfg. As supplied the list is:

Atom, Debug, Device, Environment, File, IoRing, Job,
LPC, Memory, Object, Other, Process, Registry,
Security, Synchronization, Time, Transaction and WOW64.
Download NtTrace from GitHub and build an x86 or amd64 binary.

Build instructions for Microsoft Visual Studio

At a Visual Studio command prompt type 'nmake -f NtTrace.mak'

Build the appropriate binary (32-bit or 64-bit) for your target program.

  • Windows does not support 32-bit binaries debugging 64-bit ones.
  • While you can use a 64-bit NtTrace on 32-bit programs the output from the 32-bit NtTrace is likely to be clearer.

(See Readme.txt for full details)

Version 2335 - 15-Oct-2022
Recent changes:
  • New entry points for Windows 11 22H2
  • Show command line for created processes
Version 2325 - 23-Sep-2022
Recent changes:
  • Add -nodlls option
  • Distinguish the initial process breakpoint
Version 2266 - 04-Nov-2021
Recent changes:
  • First pass at adding the Windows 11 NtDll functions
Version 2081 - 12-Sep-2021
Recent changes:
  • Add inline frame handling to the StackTrace functionality
  • Replace home-grown headers with cvconst.h, from the DIA SDK in Visual Studio
  • Remove conditional code needed for ancient versions of MSVC
Version 1918 - 24-Oct-2020
Recent changes:
  • Split NtTrace build directory into build32 and build64
  • Update NtDll for Windows 10 2004
  • Consistent logging of process header
  • Use decorated name as a fallback if unable to undecorate
Version 1914 - 15-Aug-2020
Recent changes:
  • Tracked new APIS in Windows 10 (up to build 2004)
  • Fix crash in exception logging (issue #3)
  • Changed email address
Version 1818 - 18-Mar-2019
Recent changes:
  • Added the most recent Windows 10 APIs, and categorized some of them
  • Update some enumerations, for example Power Information, with newer values
  • Support for user32 and gdi32 on more recent versions of Windows that use win32u.dll
  • Add -v option to NtTrace to display address and SSN
Version 1439 - 16-Oct-2014
Recent changes:
  • Clean compile with VC14 (CTP3)
  • Add filter off logic
Version 1396 - 03-Oct-2013
Recent changes:
  • Ctrl+C now detaches from attached process (-a option) rather than terminating
  • Add -nl option to force a newline on each output
  • A few minor changes to NTDLL/Gdi32/User32 entry points

Version 1362 - 17-Jun-2013
Change summary:
  • Add -config option to allow easier selection of configuration
  • Add Gdi32Trace.cfg containing the NtGdi functions exported from Gdi32
  • Add User32Trace.cfg containing the NtUser functions exported from User32
  • A few minor changes to NTDLL entry points
  • Better logging of 64bit C++ exceptions
  • Display of RootDirectory for ObjectAttributes

Version 1139 - 25-May-2012
Change summary:

  • Add entry points for the NtWow64 functions (available to 32-bit programs on 64-bit Windows)
  • Add names and types to a few more entry points
  • Improve handling of duplicate/output arguments

Version 967 - 17-Nov-2011
Change summary:

  • Add X64 build (AMD64) - supports 32-bit and 64-bit targets
  • Add new entry points for Windows 7
  • Extend coverage of names for enumerated values
  • Add basic LPC_MESSAGE unpacking
  • Add -pre option to trace pre-call as well as post-call
  • Don't dereference output only arguments on error
If you have any queries or comments about NtTrace, please email