Source Code Overview

Techniques Demonstrated

The source code for NTUtils demonstrates the following interesting techniques:

Requirements and Instructions for Building from Source

The source is written for the Cygwin compiler (building with -mno-cygwin to prevent run-time dependencies). It also uses UPX for reducing executable size.

Parts of the code are dependent on the Boost Library Collection. The provided Makefile assumes that the environment variable BOOST is set to the location of the Boost libraries.

The documentation is built using the Microsoft HTML Help Workshop; you have to add it to your path before running make ntutils.chm. This isn't an open-source tool, but it is freely available for download.

Usage of the Native NT API

NTUtils programs try their best not to depend on the NT API, since it is subject to change without notice. In general, it is only used to supply missing functionality on old, stable platforms (e.g., to implement OpenThread on Windows NT 4.0).

Documentation Bugs Discovered

Native NT API

The classic reference "Windows NT/2000 Native API Reference" by Gary Nebbett is used as the Native NT API documentation.

A field is missing in the SYSTEM_PROCESSES structure (officially called the SYSTEM_PROCESS_INFORMATION class by the Platform SDK). This causes any program accessing the threads array of a process to fail.

Win32 API

The GetPriorityClass function is documented as requiring the PROCESS_QUERY_INFORMATION access right. However, it will still fail for some processes under NT, even if that right is granted on the process handle. The workaround used by NTUtils programs is to always attempt to open the process handle with PROCESS_ALL_ACCESS rights, and default to PROCESS_QUERY_INFORMATION if the full access handle fails. This is a bug in NT, and is not present in later products.

Directory Structure

The src/include directory contains most of the code; that directory contains several header file libraries.

The base cpp file (e.g., src/ntsuspend.cpp) usually just contains the code for parsing options. The general framework for running as a service and single-shot named pipe communications is in src/include/ntutils/remote_framework.h. The actual implementation of the program logic is found in an inc file in the src directory (e.g., src/ntsuspend.inc).

Errors

All error messages are designed to be as verbose as reasonably possible; this results in larger executables but much less time spent debugging or discovering what the problem really is. Normal error messages are collected and sent to stdout when running as a command-line program, or sent across the network when running as a service. Fatal error messages are sent to stderr when running as a command-line program, or are sent to OutputDebugString when running as a service.