Inside the Native API

Copyright (C) 1998-2004 Mark Russinovich
Last Updated: Last updated November 23, 2004

Introduction

Virtually everybody familiar with NT has at the minimum heard that there is a hidden API that NT uses internally. This API, which is called the Native API, is almost entirely hidden from view, with only a handful of its function documented in generally accessible publications. This obfuscation has lead to a general belief that the Native API can provide applications magical powers, perhaps even allowing them to bypass security measures implemented by standard APIs like Win32. Thoughts along these lines usually lead to the Native API conspiracy theory: Microsoft is keeping the API for themselves and their own application to unfair advantage. The native API does expose some nuances not available through documented APIs (for example, you can specify whether or not file opens should be case sensitive, something not possible with Win32's CreateFile() or OpenFile()), however the majority of the APIs capabilities are accessible through documented channels.

This article will introduce you to the Native API and provide you a roadmap for what is in the API. I'll first describe what the Native API is, how it's invoked in normal operation, and how its used as a support infrastructure for the APIs of NT's operating environment subsystems. Then I'll take you on a tour of the API where I break it down into sets of related functions (memory management, synchronization, etc.). I'll talk about the capabilities available through the API's functions and note Win32 APIs that map to particular Native APIs where applicable. This comprehensive look at the Native API should help clarify misconceptions about how it's used, why it's used, and what the undocumented APIs are hiding from us (e.g. whether the conspiracy theory has validity).

Native API Architecture

The Windows NT Native API serves one purpose: as a means for calling operating system services located in kernel mode in a controlled manner. Kernel mode is where the core of NT executes, and it's in kernel mode that components have direct access to hardware and services that perform management of the computer's resources including memory, devices and processes. Thus, whenever a program executing in user mode wants to perform I/O, allocate or deallocate virtual memory, start a thread or process, or interact with global resources, it must call upon one or more services that live in kernel mode.

The Native API is equivalent to the system call interface on traditional monolithic operating systems such as most UNIXes. On most UNIXes, however, the system call interface is well documented and is generally available for use by standard applications. For example, the read() call for reading data from a file, socket, or input device in most flavors of UNIX is a system call that is handled by code in kernel mode. In Windows NT the Native API, its system call interface, is hidden from programmers behind higher level APIs such as Win32, OS/2, POSIX or DOS/Win16. The reason behind this is NT's architecture.

NT is a "modified microkernel" architecture. Instead of supporting one basic operating system API, NT implements several. It does this efficiently by implementing operating environment subsystems in user mode that export particular APIs to client programs. The "national language" API of NT is Win32, and the Win32 architecture demonstrates this concept. The Win32 operating environment subsystem is divided among a server process, CSRSS.EXE (Client/Server Runtime SubSystem), and client-side DLLs that are linked with programs that use the Win32 API. The core of the Win32 API is divided into three categories: windowing and messaging, drawing, and base services. Windows and messaging APIs include CreateWindow() and SendMessage(), and are exported to Win32 programs via the USER32.DLL library. BitBlt() and LineTo() are Win32 drawing functions and are provided in GDI32.DLL. Finally, base services include all Win32 I/O, process and thread, memory management, and synchronization APIs, and KERNEL32.DLL is the library that exports them.

When a Win32 program calls a Win32 API control is transferred within its address space into one of Win32's client-side DLLs. The DLL can execute one or more of the following options:

The first option of returning to the caller is rarely possible and is only possible when the DLL can service the function without the help of operating system services. An example of this is GetCurrentProcess(). This API simply returns a handle to the current process that is cached in KERNEL32 when the process is started.

The second option is also rarely required. A client-side DLL only needs to send messages to the Win32 server when the server must participate with, and be aware of, the function's execution. The Win32 server creates a Win32 execution environment for its clients that involves maintaining some state associated with its client processes. Thus, the CreateProcess() API, exported by KERNEL32, requires an interaction with the Win32 server. The server in this case prepares a new process for execution by mapping in an executable image, creating a command-line argument structure, and so on. The Win32 server calls Native API functions to create the actual process image and prepare its address map.

The final option is the most frequently exercised. Let's talk about USER32 and GDI32 APIs first, before talking about KERNEL32's use of Native APIs. In versions of NT prior to 4.0, windowing and drawing functions were located in the Win32 server (CSRSS.EXE). This meant that whenever an application used these function a message would be sent to the server. In NT 4.0 the windowing and drawing components of Win32 were moved into a kernel mode component named WIN32K.SYS. Instead of sending a message to the server, the client-side DLLs just call directly into the kernel, saving the overhead of messaging and context switching to another process. This has enhanced NT's graphics performance (as evidenced by the Pinball sample game). GDI and USER functions have become NT's second Native API, but they are less mysterious than the primary Native API since drawing, windowing, and messaging APIs are well-documented.

KERNEL32 functions that call the Native API directly include all of its I/O (e.g CreateFile(), ReadFile(), WriteFile()), synchronization (e.g. WaitForSingleObject(), SetEvent()), and memory management (e.g. VirtualAlloc(), VirtualProtect()) functions. In fact, the majority of KERNEL32's exported routines use the Native API directly. The figure below shows the flow of control from a Win32 application executing a Win32 call (CreateFile()), through KERNEL32, NTDLL, and into kernel mode where control is transferred to the NtCreateFile system service. I'll talk about this process in detail.

Win32 application flow of control

NTDLL.DLL

The Native API is provided to user-mode programs by the NTDLL.DLL library. NTDLL.DLL, besides containing Native API user-mode entry points, has process startup and module loading code in it. The bulk of it, though, are the Native API stubs that transfer control to kernel mode. This is accomplished by executing a software exception. If you look at a stub for a Native API in NTDLL inside of a debugger you'll see something like this (on x86):

NtCreateFile:
    mov    eax, 0x0000001A
    lea    edx, [esp+04]
    int    0x2E 
    ret    0x2C

In this case the call is NtCreateFile but every other native call looks almost identical. The first instruction is loading a register with the Native API's index number. Every Native API has a unique index number, which is generated automatically by a script that runs as part of the NT build process. Thus, the index number for a specific function can vary from build to build as Native APIs are added and removed. The second instruction loads a register with a pointer to the call's parameters. Next is the software exception instruction. NT registers a kernel-mode exception handler specifically for handling Native API software exceptions. On x86's this exception is 0x2E. The final instruction pops the parameters off the caller's stack. Note that on Windows 2000 and higher Windows uses special processor instructions when available instead of INT 0x2E. On Intel systems it uses SYSENTER and on AMD systems it uses SYSCALL.

Note that all of the Native APIs begin with "Nt". The export table in NTDLL.DLL also makes the Native API accessible through an alternate naming convention, one where command names begin with "Zw" instead of "Nt". Thus, ZwCreateFile() is an alias for NtCreateFile().

The Native API exception handler in kernel mode is named KiSystemService, and it is invoked whenever a Native API is executed in user mode. Its task is to determine if the API's index number is valid, and if so, pass control to the appropriate system service in kernel mode to service the request. It does this by simply using the index number passed from user mode to index into an array called KiSystemServiceTable. Each entry in this array includes a pointer to the appropriate function and the number of parameters the function expects. KiSystemService takes the parameters passed on the user mode stack (pointed to in the edx register on x86) and pushes them on the kernel stack before calling the function specified in the array for the index.

Win32 Native APIs introduced in NT 4.0 are handled by the same exception handler, but the index numbers of Win32 functions specify that a second array of system service pointers should be used. The function pointers in the second array reference functions in WIN32K.SYS.

Each system service performs operations specific to the API they implement, of course, but most of them must deal with the validation of the parameters passed to them from user mode. Many parameters are pointers, and dereferencing an invalid pointer in kernel mode without taking precautionary measures can prove catastrophic. Validating parameters is straight-forward, but the number of Native APIs and the number of parameters they take have made getting it right tough for Microsoft. In 1997 I wrote a program called NTCrash that barraged the Native API interface with garbage parameters. The program discovered 13 WIN32K system services that failed to perform comprehensive parameter validation, the result of which were Blue Screens. Microsoft closed these holes in Service Pack 1.

About year later I revisited NTCrash and tweaked it to be more intelligent about generating garbage - the garbage this new version, NTCrash2, produces hits boundary conditions that can be easy to miss in validation. In fact, this revision found 40 more APIs (15 Native APIs and 25 WIN32K Native APIs) with Blue Screen holes. Microsoft has been made aware of the holes and they will be closed in Service Pack 4. Testers within Microsoft have told me that they use a greatly enhanced version of my NTCrash to test system call interfaces.

After parameter validation, system services usually call functions supplied by NT's Executive subsystems. These subsystems all live in kernel mode, and each is responsible for managing certain resources. Example subsystems include the Process Manager, Virtual Memory Manager, I/O Manager, and Local Procedure Call facility.

Native API Catalog

There are about 240 Native APIs in Win2K, up from around 200 in NT 3.5.1. In this section I break the Native API down into categories of related functions and I start each category by briefly describing the capabilities of the group. For each function I list Win32 functions that obtain functionality similar to that provided by the Native API (which they usually do by actually calling upon the Native API).

Currently, the only documentation on Native APIs is located in the Windows NT Device Driver Kit (DDK) and the Windows NT Installable File System Kit (IFS Kit). The DDK actually describes the parameters and usage of a around 25 Native APIs, and includes prototype and parameter information for a few others in NTDDK.H (e.g. NtQueryInformationProcess(). The IFS Kit documents about 25 more APIS only by providing prototypes in header files that come as part of the kit, and sometimes through their use in sample code. Most of APIs included in the IFS Kit are in the file I/O and security categories. The IFS Kit is available from Microsoft for a fee after signing an NDA (see Microsoft's Web site for information). You can find prototypes and some minimal documentation for many Native APIs in the third-party book Windows NT/2000 Native API Reference.

The format of the following tables is as follows: Column 1 shows the native API, column 2 shows Win32 functions that map to the API, column 3 provides a brief description of the APIs functionality, and column 4 shows if its documented in the DDK or not (either explicitly or by its prototype). Functions new to Win2K are shown in red, those new to XP in blue, and those new to Server 2003 in green.

File Maps

Special Files
These APIs are used to create files that have custom characteristics.
NtCreateMailslotFile CreateMailSlot Creates a mailslot end-point.    
NtCreateNamedPipeFile CreateNamedPipe Creates a named-pipe end-point.  
NtCreatePagingFile   The System applet uses this API to create paging files. Parameters specify the name, as well as minimum and maximum size.    
 
Drivers
These functions are used by NT to load and unload device driver images from system memory.
NtLoadDriver CreateFile with Service Control Manager Loads a device driver based on information provided under HKLM\System\CurrentControlSet\Services\driver name    
NtUnloadDriver Service Control Manager supported Unloads the specified driver from memory, presuming the driver supports an unload interface.  
NtRegisterNewDevice   NT 3.51 only.    
 
Processor and Bus
Processor registers and components can be controlled via these functions.
NtFlushInstructionCache   The NT kernel debugger uses this API, which flushes the processor instruction cache using the HAL.    
NtFlushWriteBuffer   The processor's memory write buffer is flushed by this function, which uses the HAL.  
NtSetLdtEntries   X86 Local Descriptor Table entries are initialized using this function.    
NtEnumerateBus   NT 3.51 only.    
NtGetCurrentProcessorNumber   New to Server 2K3. Gets the number of the processor on which a thread is executing.  
 
Debugging and Profiling
The profiling APIs provide a mechanism for sample-based profiling of kernel-mode execution. The Kernprof tool in the DDK makes use of them, and a recent Windows Developer's Journal presented a source code to a Kernprof clone. The debug control function is used by WinDbg for obtaining internal kernel information and controlling thread and process execution.
NtCreateProfile   Creates a profile object.    
NtQueryIntervalProfile   Returns profiled data.  
NtSetIntervalProfile   Specified sampling interval.    
NtStartProfile   Starts sampling.    
NtStopProfile   Stops sampling.    
NtSystemDebugControl   Implements a range of debugger support commands.    
NtRegisterThreadTerminatePort   A debugger registers for thread termination notification with this API.    
NtCreateDebugObject   New to WinXP. Creates a debug object.    
NtDebugActiveProcess DebugActiveProcess New to WinXP. Enables a debugger to attach to an active process and debug it.    
NtDebugContinue Continue DebugEvent New to WinXP. Allows a process to contiue a thread that has generated a debug event.    
NtQueryDebugFilterState   New to WinXP. Queries the debug filter state level for a specific component.    
NtRemoveProcessDebug DebugActiveProcessStop New to WinXP. Stops debugging the specified process.    
NtSetDebugFilterState   New to WinXP. Sets the debug output filter level for the specified component.    
NtSetInformationDebugObject New to WinXP. Sets the attributes of a debug object.  
NtWaitForDebugEvent WaitForDebugEvent New to WinXP. Waits for a debugging event on a process being debugged.  
 
Channels
These functions were introduced in NT 4.0 and are present in Win2K Beta 1. However, they are all stubs that return STATUS_NOT_IMPLEMENTED. Their names imply that they were intended to provide access to a communications mechanism. Why are they in the released versions of NT if they are not implemented?
NtCreateChannel   Not implemented.    
NtOpenChannel   Not implemented.  
NtListenChannel   Not implemented.    
NtSetContextChannel   Not implemented.    
NtReplyWaitSendChannel   Not implemented.    
NtSendWaitReplyChannel   Not implemented.    
 
Power
There's only one Native API for power management in NT 4.0. Interestingly, this API was introduced in NT 4.0, but was a stub that returned STATUS_NOT_IMPLEMENTED. Win2K fleshes out the API and adds more commands.
NtSetSystemPowerState   Not implemented in NT 4.0.    
NtInitiatePowerAction   New to Win2K. Initiate a power event (e.g. suspend)    
NtPowerInformation GetSystemPowerStatus New to Win2K. Get the system's power state.    
NtSetThreadExecutionState SetThreadExecutionState New to Win2K. Sets a thread's system power state requirement.    
NtRequestWakeupLatency   New to Win2K. Sets a process' wakeup latency.    
 
Plug-and-Play
Like the Power API, some of these were introduced in NT 4.0 as unimplemented functions. Win2K fleshes them out and adds more.
NtGetPlugPlayEvent   Present, but not implemented in NT 4.0. Sets plug and play events.    
NtPlugPlayControl   Present, but not implemented in NT 4.0. Sends commands to the plug-and-play subsystem.  
 
Objects
Object manager namespace objects are created and manipualted with these routines. A couple of these, like NtClose, are general in that they are used with any object type.
NtClose CloseHandle Closes a handle to any object type. DDK
NtDuplicateObject DuplicateHandle Duplicates a handle to an object.  
NtCreateDirectoryObject   Creates a directory in the object manager namespace. DDK
NtCreateSymbolicLinkObject   Creates a symbolic link in the object manager namespace. The Win32 DefineDosDevice command lets you create links, but only in the \?? subdirectory. DDK
NtMakeTemporaryObject   Causes a permanent object to be deleted during NT shutdown so that it isn't present at the next boot. DDK
NtOpenDirectoryObject   Opens an object manager namespace directory.    
NtQueryDirectoryObject   Used to enumerate the objects located in an directory object.    
NtOpenSymbolicLinkObject   Opens a symbolic link object.    
NtQuerySymbolicLinkObject   Returns the name of the object that the symbolic link points at.    
NtQueryObject   Queries an an object's attributes, such as its name.    
NtSetInformationObject   Sets an object's attributes.    
NtMakePermanentObject   New to WinXP. Sets the permanent flag on an object.  
NtTranslateFilePath   New to WinXP. Translates a file path from one format (e.g. NT, ARC, EFI) to another.  
 
Registry
Win32 Registry functions basically map directly to these APIs, and many of them are documented in the DDK.
NtCreateKey RegCreateKey Creates or opens a Registry key. DDK
NtOpenKey RegOpenKey Opens an existing Registry key. DDK
NtDeleteKey RegDeleteKey Deletes a Registry key. DDK
NtDeleteValueKey RegDeleteValue Deletes a value. DDK
NtEnumerateKey RegEnumKey, RegEnumKeyEx Enumerates the subkeys of a key. DDK
NtEnumerateValueKey RegEnumValue Enumerates the values within a key. DDK
NtFlushKey RegFlushKey Flushes changes back to the Registry on disk. DDK
NtInitializeRegistry   Gets the Registry rolling. The single parameter to this specifies whether its a setup boot or a normal boot.    
NtNotifyChangeKey RegNotifyChangeKeyValue Allows a program to be notified of changes to a particular key or its subkeys.    
NtQueryKey RegQueryKey Queries information about a key. DDK
NtQueryMultiplValueKey RegQueryMultipleValues Retrieves information about multiple specified values. This API was introduced in NT 4.0.    
NtQueryValueKey RegQueryValue, RegQueryValueEx Retrieves information about a specified value. DDK
NtReplaceKey RegReplaceKey Changes the backing file for a key and its subkeys. Used for backup/restore.    
NtSaveKey RegSaveKey Saves the contents of a key and subkey to a file.    
NtRestoreKey RegRestoreKey Loads the contents of a key from a specified file.    
NtSetInformationKey   Sets attributes of a key.    
NtSetValueKey RegSetValue, RegSetValueEx Sets the data associated with a value. DDK
NtLoadKey RegLoadKey Loads a hive file into the Registry.    
NtLoadKey2   Introduced in NT 4.0. Allows for options on loading a hive.    
NtUnloadKey RegUnloadKey Unloads a hive from the Registry.    
NtCompactKeys   New to WinXP. Makes key storage adjacent.  
NtCompressKey   New to WinXP. Performs in-place compaction of a hive.  
NtLockRegistryKey   New to WinXP. Locks a registry key for modification.  
NtRenameKey   New to WinXP. Renames a Registry key.  
NtSaveKeyEx RegSaveKeyEx New to WinXP. Saves the contents of a key and its subkeys to a file.  
NtUnloadKeyEx   New to WinXP. Unloads a hive from the Registry.  
NtLoadKeyEx   New to Server 2K3. Loads a hive into the Registry.  
NtUnloadKey2   New to Serer 2K3. Unloads a hive from the Registry.  
NtQueryOpenSubKeysEx   New to Server 2003. Returns the keys opened beneath a specified key.  
 
Local Procedure Call
LPC is NT's core interprocess communications mechanism. If you use RPC between processes on the same computer you are using LPC indirectly.
NtCreatePort   Creates a port object.    
NtAcceptConnectPort   Accepts a port connection.  
NtCompleteConnectPort   Completes a connection.    
NtConnectPort   Connects a port to another port that is accepting connections.    
NtImpersonateClientOfPort   Thread impersonates the identify of the process on the other end of a port.    
NtListenPort   Listens on a port for connection requests.    
NtQueryInformationPort   Obtains information on a port.    
NtReadRequestData   Reads data associated with a port message.    
NtReplyPort   Sends a reply message.    
NtReplyWaitReceivePort   Sends a reply message and then waits for an incoming request message.    
NtReplyWaitReplyPort   Sends a reply message and then waits for an incoming reply message.    
NtRequestPort   Sends a request message.    
NtRequestWaitReplyPort   Sends a request message and waits for an incoming reply message.    
NtWriteRequestData   Fills in data for a request message    
NtSecureConnectPort   New to Win2K. Creates a secure connection port.    
NtQueryPortInformationProcess New to WinXP. Used to determine if a process has an associated exception or debug port.  
 
Security
The Native security APIs are mapped almost directly by Win32 security APIs.
NtAccessCheck AccessCheck Checks to see whether current thread has access to an object based on its security descriptor.    
NtAccessCheckAndAuditAlarm AccessCheckAuditAlarm Generates an audit message related to access checking.    
NtAdjustGroupsToken AdjustTokenGroups Adds or removes groups associated with a token.    
NtAdjustPrivilegesToken AdjustTokenPrivileges Enables or disables privileges associated with a token.    
NtCloseObjectAuditAlarm ObjectCloseAuditAlarm Generates an audit message indicating that an object was closed.    
NtCreateToken CreateToken Creates a token object.    
NtDeleteObjectAuditAlarm ObjectDeleteAuditAlarm Generated an audit event indicating that an object was deleted.    
NtDuplicateToken DuplicateToken, DuplicateTokenEx Duplicates a token object.    
NtImpersonateThread ImpersonateLoggedOnUser Allows a thread to impersonate the identity of another user.    
NtOpenObjectAuditAlarm ObjectOpenAuditAlarm Generated an audit event indicating that an object was opened.    
NtOpenProcessToken OpenProcessToken Obtains a handle to the token of a specified process.    
NtOpenThreadToken OpenThreadToken Opens a handle to the token of a specified thread.    
NtPrivilegeCheck PrivilegeCheck Checks to see whether a token has the specified privileges enabled.    
NtPrivilegeObjectAuditAlarm ObjectPrivilegeAuditAlarm Generates an audit event record associated with a privilege check.    
NtPrivilegedServiceAuditAlarm PrivilegedServiceAuditAlarm Generates an audit message indicating the attempt to use specified privileges.    
NtQueryInformationToken GetTokenInformation Obtains information about a token.    
NtQuerySecurityObject GetUserObjectSecurity, GetPrivateObjectSecurity Retrieves information about an object's security settings.    
NtSetInformationToken SetTokenInformation Sets a token's attributes.    
NtSetSecurityObject SetUserObjectSecurity, SetrivateSecurityObject Sets the security information of an object.    
NtAccessCheckByType AccessCheckByType New object-specific security support in Win2K.    
NtAccessCheckByTypeAndAuditAlarm AccessCheckByTypeAndAuditAlarm New object-specific security support in Win2K.    
NtAccessCheckByTypeResultList AccessCheckByTypeResultList, AccessCheckByTypeResultListAndAuditAlarm New object-specific security support in Win2K.    
NtFilterToken CreateRestrictedToken New object-specific security support in Win2K.    
NtCompareToken New to WinXP. Compares two tokens.  
NtOpenProcessTokenEx New to WinXP. Opens a process token.  
NtOpenThreadTokenEx New to WinXP. Opens a thread token.  
 
Processes and Threads
These functions control processes and threads. Many have direct Win32 equivalents.
NtAlertResumeThread   Resumes a thread.    
NtAlertThread   Sends an alert to a thread.    
NtTestAlert   Tests for whether a thread has a pending alert.    
NtCreateProcess CreateProcess Creates a new process.    
NtCreateThread CreateThread Creates a new thread.    
NtCurrentTeb   Returns a pointer to a thread's environment block.    
NtDelayExecution Sleep, SleepEx Pauses a thread for a specified time.    
NtGetContextThread GetThreadContext Retrieves the hardware context (registers) of a thread.    
NtSetContextThread SetThreadContext Sets the hardware context (registers) of a thread.    
NtOpenProcess OpenProcess Opens a handle to a specified process. DDK
NtOpenThread OpenThread Opens a handle to a specified thread.    
NtQueryInformationProcess GetProcessTimes, GetProcessVersion, GetProcessWorkingSetSize, GetProcessPriorityBoost, GetProcessAffinityMask, GetPriorityClass, GetProcessShutdownParameters Obtains information about a process' attributes. DDK
NtQueryInformationThread GetThreadTimes, GetThreadPriority, GetThreadPriorityBoost Obtains information about a thread's attributes. DDK
NtQueueApcThread QueueUserApc Introduced in NT 4.0. Queues an Asynchornous Procedure Call to a thread.    
NtResumeThread ResumeThread Wakes up a suspended thread.    
NtSetInformationProcess SetProcessAffinityMask, SetPriorityClass, SetProcessPriorityBoost, SetProcessShutdownParameters, SetProcessWorkingSetSize Sets a process' attributes. DDK
NtSetInformationThread SetThreadAffinityMask, SetThreadIdealProcessor, SetThreadPriority, SetThreadPriorityBoost Sets a thread's attributes. DDK
NtSetLowWaitHighThread   NT 4.0 only (not in Win2K).    
NtSetHighWaitLowThread   NT 4.0 only (not in Win2K).    
NtSuspendThread SuspendThread Suspends a thread's execution.    
NtTerminateProcess TerminateProcess Deletes a process.    
NtTerminateThread TerminateThread Deletes a thread.    
NtYieldExecution SwitchToThread Introduced in NT 4.0. Causes thread to give up CPU.    
NtCreateProcessEx   New to WinXP. Creates a new process.  
NtResumeProcess   New to WinXP. Resumes a suspended process.  
NtSuspendProcess   New to WinXP. Suspends a process.  
NtApphelpCacheControl New to Server 2003. Controls the application-compatibility shim cache.  
 
Atoms
Atoms allow for the efficient storage and referencing of character strings.
NtAddAtom AddAtom Introduced in NT 4.0. Adds a character string to an atom table.    
NtDeleteAtom DeleteAtom Introduced in NT 4.0. Removes an atom from an atom table.    
NtFindAtom FindAtom Introduced in NT 4.0. Looks up an atom in an atom table.    
NtQueryInformationAtom GetAtomName Introduced in NT 4.0. Retrieves information about an atom.    
 
Error Handling
Device drivers and debuggers rely on these error handling routines.
NtRaiseException RaiseException Signals an exception condition to trigger exception handler execution.    
NtContinue try/except Allows error processing handling to continue to the next handler.    
NtRaiseHardError   Used to raise an error message box.  
NtSetDefaultHardErrorPort SetErrorMode Used by programs to disable hard error message boxes cause by their actions.  
 
Execution Environment
These functions are related to general execution environment.
NtQueryDefaultLocale GetLocaleInfo Retrieves information about the locale.  
NtSetDefaultLocale SetLocaleInfo Sets locale information.  
NtQuerySystemEnvironmentValue GetEnvironmentVariable Gets the value of an environment variable.  
NtSetSystemEnvironmentValue SetEnvironmentVariable Sets the value of an environment variable.  
NtQueryDefaultUILanguage   New to Win2K. Win2K supports on-the-fly language changes. Queries the current language.    
NtSetDefaultUILanguage   New to Win2K. Win2K supports on-the-fly language changes. Sets the current language.    
NtEnumerateSystemEnvironmentValuesEx New to WinXP. Enumerates the system environment variables.  
NtQuerySystemEnvironmentValueEx New to WinXP. Queries the value of an environment variable.  
 
Timers and System Time
Virtually all these routines have functionality accessible via Win32 APIs.
NtCancelTimer CancelWaitableTimer, timeKillEvent Cancels a timer.  
NtCreateTimer CreateWaitableTimer Creates a timer.  
NtOpenTimer OpenWaitableTimer Opens a timer object.  
NtQueryTimer   Queries a timer's attributes.  
NtQueryTimerResolution timeGetDevCaps Queries the system's timer resolution.  
NtSetTimer timeSetEvent Sets a timer for an expiration event.  
NtSetTimerResolution timeBeginPeriod, timeEndPeriod Sets the system timer resolution.  
NtQueryPerformanceCounter QueryPerformanceCounter, QueryPerformanceFrequency Queries the system performance counter.  
NtQuerySystemTime GetSystemTime Gets the current time.  
NtSetSystemTime SetSystemTime Sets the system time.  
NtGetTickCount GetTickCount Get the ticks since system boot.  
 
Synchronization
Most synchronization objects have Win32 APIs, with the notable exception of event pairs. Event pairs are used for high-performance interprocess synchronization by the LPC facility.
NtCreateEvent CreateEvent Creates an event object.  
NtOpenEvent OpenEvent Opens an event object.  
NtClearEvent   Clears the signalled state of an event.  
NtPulseEvent PulseEvent Signals an event and then resets it.  
NtQueryEvent   Queries the state of an event.  
NtResetEvent ResetEvent Resets an event to a non-signalled state.  
NtSetEvent SetEvent Sets an event to the signalled state.  
NtCreateEventPair   Creates an event pair.  
NtOpenEventPair   Opens an event pair.  
NtSetHighEventPair   Sets the high half of an event pair to signalled state.  
NtSetHighWaitLowEventPair   Sets the high half of an event pair to signalled state and waits for the low half to become signalled.  
NtSetLowEventPair   Sets the low half of an event pair.  
NtSetLowWaitHighEventPair   Sets the low half of an event pair and waits for the high-half to become signalled.  
NtWaitHighEventPair   Waits for the high-half of an event pair to become signalled.  
NtWaitLowEventPair   Waits for the low-half of an event pair to become signalled.  
NtCreateMutant CreateMutex Creates a mutant object (known as a mutex in user mode).  
NtOpenMutant OpenMutex Opens a mutant object (known as a mutex in user mode).  
NtQueryMutant   Queries the state of a mutant object.  
NtReleaseMutant ReleaseMutex Signals a mutant  
NtReleaseProcessMutant   3.51 only.  
NtReleaseThreadMutant   3.51 only.  
NtCreateSemaphore CreateSemaphore Creates a semaphore object.  
NtOpenSemaphore OpenSemaphore Opens a semaphore object.  
NtQuerySemaphore   Queries the state of a semaphore.  
NtReleaseSemaphore ReleaseSemaphore Signals a semaphore.  
NtSignalAndWaitForSingleObject   Introduced in NT 4.0. Signals a synchornization object and then waits for it to be signalled again.  
NtWaitForMultipleObjects WaitForMultipleObjects, WaitForMultipleObjectsEx Waits for multiple objects to become signalled.  
NtWaitForSingleObject WaitForSingleObject, WaitForSingleObjectEx Waits for a single object to become signalled.  
NtCreateKeyedEvent New to WinXP. Creates a keyed event object.  
NtOpenKeyedEvent New to WinXP. Opens a named keyed event object.  
NtReleaseKeyedEvent New to WinXP. Signals a keyed event object.  
NtWaitForKeyedEvent New to WinXP. Waits for a keyed event to become signalled.  
NtSetEventBoostPriority New to WinXP. Signals an event and sets the priority of woken threads.  
 
Memory
Most of NT's virtual memory APIs are accessible via Win32.
NtAllocateVirtualMemory VirtualAlloc, VirtualAllocEx Allocates virtual memory.    
NtFreeVirtualMemory VirtualFree, VirtualFreeEx Frees virtual memory.    
NtQueryVirtualMemory VirtualQuery, VirtualQueryEx Queries a range of virtual memory's attributes.    
NtProtectVirtualMemory VirtualProtect, VirtualProtectEx Sets the protection for a range of virtual memory.    
NtLockVirtualMemory VirtualLock Locks a range of virtual memory.    
NtUnlockVirtualMemory VirtualUnlock Unlocks a range of virtual memory.    
NtReadVirtualMemory ReadProcessMemory Reads a range of virtual memory from a specied process.    
NtWriteVirtualMemory WriteProcessMemory Writes a range of virtual memory from a specied process.    
NtFlushVirtualMemory FlushViewOfFile Flushes a memory mapped range of memory to the file on disk.    
NtCreateSection CreateFileMapping Creates a range of memory backed by a file.    
NtOpenSection OpenFileMapping Opens a named memory mapping section object. DDK
NtExtendSection   Extends an existing range of virtual memory backed by a file.    
NtMapViewOfSection MapViewOfFile Maps a portion of a file into virtual memory. DDK
NtUnmapViewOfSection UnmapViewOfFile Unmaps a portion of virtual memory backed by a file. DDK
NtAllocateVirtualMemory64 VirtualAllocVlm New to Win2K. Allocates 64-bit virtual memory.    
NtFreeVirtualMemory64 VirtualFreeVlm New to Win2K. Frees 64-bit virtual memory.    
NtMapViewOfVlmSection MapViewOfFileVlm New to Win2K. Maps a file into 64-bit virtual memory.    
NtUnmapViewOfVlmSection UnmapViewOfFileVlm New to Win2K. Unmaps a view of a file mapped into 64-bit virtual memory.    
NtAreMappedFilesTheSame   New to Win2K. The loader uses this to efficiently see if a given file has already been mapped into memory.    
NtProtectVirtualMemory64 VirtualProtectVlm New to Win2K. Sets protection on 64-bit virtual memory.    
NtQueryVirtualMemory64 VirtualQueryVlm New to Win2K. Queries the attributes of 64-bit virtual memory.    
NtReadVirtualMemory64 ReadProcessMemoryVlm New to Win2K. Reads data from 64-bit memory of the specified process.    
NtWriteVirtualMemory64 WriteProcessMemoryVlm New to Win2K. Writes data to 64-bit memory of the specified process.    
 
File and General I/O
File I/O is the best documented of the native APIs since many device drivers must make use of it.
NtCancelIoFile CancelIo Cancels an I/O request.    
NtCreateFile CreateFile, CreateDirectory, CreateDirectoryEx Create or opens a file, directory or device object. DDK
NtCreateIoCompletion CreateIoCompletionPort Tells the I/O manager that a thread wishes to be notified when an I/O completes.    
NtOpenIoCompletion   Opens a named I/O completion object.    
NtSetIoCompletion   Sets an I/O completion object's attributes.    
NtQueryIoCompletion   Retrieves specific information about an I/O completion object.    
NtRemoveIoCompletion   Removes an I/O completion callback.  
NtDeleteFile DeleteFile Deletes a file object.    
NtDeviceIoControlFile DeviceIoControl Sends an IOCTL to a device's device driver, which represented by an open file object.    
NtFlushBuffersFile FlushFileBuffers Flushes in-memory file data to disk.    
NtFsControlFile DeviceIoControl Sends an I/O control (IOCTL) to a driver represented by an open device object. These are typically used for file system-related special commands.    
NtLockFile LockFile, LockFileEx Locks a range of a file for synchronized access.    
NtUnlockFile UnlockFile Unlocks a range of a file for synchronized access.    
NtNotifyChangeDirectoryFile FindFirstChangeNotification, FindNextChangeNotification Registers that a thread wishes to be notified when a directory's contents change.    
NtOpenFile OpenFile Opens an existing file.    
NtQueryAttributesFile GetFileAttributesEx Gets a file's attributes.    
NtQueryDirectoryFile FindFirstFile, FindFirstFileEx, FindNextFile Retrieves a directory's contents.    
NtQueryEaFile   Retrieves a file's extended attributes.    
NtSetEaFile   Sets the extended attributes of a file.    
NtQueryFullAttributesFile   Introduced in NT 4.0. Gets a file's full attributes.    
NtQueryInformationFile GetShortPathName, GetLongPathName, GetFullPathName, GetFileType, GetFileSize, GetFileTime Retrieves specific information regarding a file. DDK
NtSetInformationFile SetEndOfFile, SetFileAttributes, SetNamedPipeHandleState, SetMailslotInfo Sets specific information regarding a file. DDK
NtQueryVolumeInformationFile GetDiskFreeSpace, GetDriveType Retrieves specific information regarding a disk volume.    
NtSetVolumeInformationFile SetVolumeLabel Sets information about a volume.    
NtReadFile ReadFile, ReadFileEx Reads data from a file. DDK
NtWriteFile WriteFile, WriteFileEx Writes data to a file. DDK
NtReadFileScatter ReadFileScatter Introduced in NT 4.0 SP2 for SQL Server. Reads data from a file into virtually discontiguous buffers.  
NtWriteFileGather WriteFileGather Introduced in NT 4.0 SP2 for SQL Server. Writes data to a file from virtually discontiguous buffers.  
NtQueryQuotaInformationFile IDiskQuotaControl:: New to Win2K. Win2K supports NTFS disk quotas. Queries disk quota information.    
NtSetQuotaInformationFile IDiskQuotaControl:: New to Win2K. Win2K supports NTFS disk quotas. Sets disk quota information.    
NtReadFile64 ReadFileVlm New to Win2K. Reads data from a file into 64-bit virtual memory.    
NtWriteFile64 WriteFileVlm New to Win2K. Writes data to a file from 64-bit virtual memory.    
 
Miscellaneous
These functions don't fall neatly into other categories.
NtAllocateLocallyUniqueId AllocateLocallyUniqueId Allocates an ID that is unique to the system with respect to other IDs allocate by this function. The security subsystem makes extensive use of this.    
NtAllocateUuids   Allocates UUIDs.    
NtDisplayString   Displays a string on the Blue Screen. This is used both during system boot and for writing on the Blue Screen of Death.    
NtQuerySystemInformation   While this function isn't directly documented, the Performance Counters in the Registry export much of the information obtainable via this call.    
NtSetSystemInformation   Various administrative applets use this function. For instance, quantum boosting is set with this API.    
NtShutdownSystem ExitWindows Shuts down NT with options for rebooting.    
NtVdmControl   Sends commands to a Virtual DOS Machine.    
NtCallbackReturn   For returning from Win32 into a caller.    
NtW32Call   For calling into Win32 user mode.    
NtQueryOleDirectoryFile   NT 4.0 only.    
NtLockProductActivationKeys New to WinXP. Locks the product activation keys for writing.  
 
Jobs
These functions implement Job objects, which are new to Win2K. They are essentially a group of associated processes that can be controlled as a single unit and that share job-execution time restrictions.
NtCreateJobObject CreateJobObject New to Win2K. Creates a job object.    
NtOpenJobObject OpenJobObject New to Win2K. Opens a named Job Object.    
NtQueryInformationJobObject QueryInformationJobObject New to Win2K. Retrieves information about a Job Object.    
NtAssignProcessToJobObject AssignProcessToJobObject New to Win2K. Assigns a process to a Job Object.    
NtSetInformationJobObject SetInformationJobObject New to Win2K. Sets a Job Object's attributes (e.g. priority).    
NtTerminateJobObject TerminateJobObject New to Win2K. Terminates a Job Object, which terminates all of its associated processes.    
NtCreateJobSet New to WinXP. Creates a job set from multiple job objects.  
 
IA64 Boot.ini
These functions are for managing the IA64 version of Boot.ini, which is stored in non-volatile RAM. On non-IA64 systems these return STATUS_NOT_IMPLEMENTED.
NtAddBootEntry   New to WinXP. Adds an entry to the boot menu.  
NtDeleteBootEntry   New to WinXP. Deletes an entry from the boot menu.  
NtEnumerateBootEntries   New to WinXP. Enumerates the boot menu entries.  
NtModifyBootEntry   New to WinXP. Modifies an existing boot menu entry.  
NtQueryBootEntryOrder   New to WinXP. Queries the order of boot menu entries.    
NtQueryBootOptions   New to WinXP. Queries the options associated with a boot menu entry.    
NtSetBootEntryOrder   New to WinXP. Sets the order of boot menu entries.  
NtSetBootOptions   New to WinXP. Sets the options associated with a boot menu entry.  
 
EFI Drivers
These functions are for managing IA64 Extensible Firmware Interface device drivers. On non-IA64 systems these return STATUS_NOT_IMPLEMTNED.
NtAddDriverEntry   New to Server 2003. Adds a driver.  
NtDeleteDriverEntry   New to Server 2003. Deletes a driver entry.  
NtEnumerateDriverEntries   New to Server 2003. Enumerates driver entries.  
NtModifyDriverEntry   New to Server 2003. Modifies an existing driver entry.  
NtQueryDriverEntryOrder   New to Server 2003. Queries the order of driver entries.    
NtSetDriverEntryOrder New to Server 2003. Sets the order of driver entries.  
 

Back to Top