Section 8: APIs

The Big Picture: How Programs Ask Windows for Help

An API (Application Programming Interface) is a menu of functions that a program may call to ask the OS to do something. "Create a file", "make a window", "start a thread": each is one function on the menu.

Windows has several menus at different heights. Higher ones are easy and safe. Lower ones are closer to the kernel.

  Easier, higher level                          Closer to the kernel
 ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
 │ .NET / UWP │→ │   Win32    │→ │  Native    │→ │  System    │→ KERNEL
 │ classes    │  │  functions │  │  API       │  │  call      │
 │            │  │ (kernel32) │  │ (ntdll)    │  │ (syscall)  │
 └────────────┘  └────────────┘  └────────────┘  └────────────┘

8.1 Win32 API (Primary)

What it is: The Win32 API is the official, documented menu for Windows programs. Despite the name "32", it is used for both 32-bit and 64-bit programs (the name stuck from the 32-bit era; the 64-bit version is sometimes called Win64, but the API is the same).

Where it lives. In the subsystem DLLs from Section 4.1:

Reading a function name. CreateFileW ends with W for "wide" (Unicode text, 16-bit characters). An A version (CreateFileA) exists for old "ANSI" text.

Why programmers like it. It is stable (Microsoft keeps old functions working for decades), documented (on Microsoft's website) and works the same on every Windows version. This is the main reason that old programs still run.

What it does inside. A Win32 function usually checks its inputs, translates them, and then calls the Native API (next topic). CreateFileW is a good example: it turns C:\file.txt into the NT form \??\C:\file.txt and calls NtCreateFile.

8.2 Native API (Lower Level)

What it is: The Native API is the lowest user-mode menu. It lives in ntdll.dll and its function names start with Nt (or Zw). These are the real entry points into the kernel.

Examples:

Mostly undocumented. Microsoft documents some of these functions but warns they may change between versions. Normal programs should stay with Win32. Security tools, some game protection and malware analysts care about the Native API because it is the last stop before the kernel.

Nt vs Zw. In user mode (ntdll.dll) NtCreateFile and ZwCreateFile are nearly the same. They differ for driver writers: a driver that calls the Zw... version tells the kernel "this request comes from trusted kernel code", so the kernel skips the argument checks it normally does for user programs. Mixing them up is a classic driver bug, so drivers must pick carefully.

The special job of ntdll.dll. It is the only DLL that contains the actual instruction that jumps into the kernel. Every other library goes through it. That is why it is loaded into every process, even tiny ones.

8.3 .NET (Managed Layer)

What it is: .NET is a programming platform from Microsoft that adds a managed layer on top of Win32. "Managed" means a runtime watches over the program.

How it works:

1. A programmer writes code in C#, VB.NET or F#.
2. The compiler turns it into an intermediate language (IL), not machine code.
3. At run time, the CLR (Common Language Runtime) uses a JIT (Just-In-Time) compiler to turn the IL into machine code for your CPU.
4. A garbage collector frees memory that is no longer used, so the programmer does not do it by hand.

Why use it? Safer code (fewer crashes from memory mistakes), a huge class library of ready-made tools, and the same code for many kinds of apps.

What it ends up calling. .NET is still a user-mode program. When a .NET app writes a file, the runtime calls a Win32 function (CreateFileW), which calls ntdll.dll, which makes a system call. Calling Win32 from .NET code is known as P/Invoke (Platform Invoke).

 C# code:  File.WriteAllText("a.txt", "hi")
     │
     ▼  .NET class library
 .NET runtime (CLR)
     │
     ▼  P/Invoke
 kernel32!CreateFileW  →  ntdll!NtCreateFile  →  kernel

Two flavours. The older .NET Framework is built into Windows. The newer .NET (just ".NET 5, 6, 8" and so on) is installed separately and also runs on Linux and macOS.

8.4 UWP (Modern Apps)

What it is: The Universal Windows Platform (UWP) is a modern app model. First seen in Windows 8 as "Metro" apps and extended in Windows 10, it runs apps from the Microsoft Store in a sandbox.

Key ideas:

Why it exists. Security and neatness. A classic Win32 app has the full rights of the user. A UWP app has only the rights it declared. A bad UWP app cannot read your documents unless you allowed it.

It is still the same NT underneath. UWP apps are normal processes. WinRT calls go down to Win32 and ntdll.dll, then system calls. The sandbox is made from familiar tools: access tokens, ACLs and object namespaces (Sections 3.4 and 6).

Today. Windows 10 and 11 let both worlds live together: classic Win32 apps, .NET apps and Store apps. Newer tools (such as the Windows App SDK and WinUI) let developers mix modern looks with traditional desktop power.

8.5 System Calls (Transition from User to Kernel)

What it is: A system call (syscall) is the controlled jump from user mode (ring 3) into kernel mode (ring 0). Remember Chapter 2: ring 3 code cannot just call kernel code. The CPU gives it one safe door: a special instruction.

The door. On modern 64-bit CPUs the instruction is syscall. A matching sysret returns. The jump goes to one fixed address that the kernel set up at boot, so a program cannot choose where it lands.

What a stub in ntdll.dll looks like (idea, not exact code):

NtCreateFile:
    move  the SYSTEM SERVICE NUMBER for NtCreateFile into register EAX
    syscall                   ← the CPU switches to ring 0 and jumps into the kernel
    return

The system service number is a small number that picks the function. The kernel keeps a table (the System Service Dispatch Table) and looks up the number to find the real kernel function.

Step by step:

 1. App calls    CreateFileW(...)              (kernel32, ring 3)
 2. Which calls  NtCreateFile(...)             (ntdll, ring 3)
 3. ntdll puts the service number in EAX, runs  syscall
 4. CPU switches to RING 0, jumps to the kernel's entry point
 5. Kernel saves the user's registers, switches to a kernel stack,
    checks the arguments (never trust ring 3!)
 6. Kernel looks up the service number in its table
 7. Runs the function:  I/O Manager → driver stack → device
 8. Kernel puts the result in a register, runs sysret
 9. CPU back to RING 3, the app gets its answer

Why the checks matter. The pointers a program passes could be lies (pointing into kernel memory, for example). The kernel probes and validates every argument before using it. This is what keeps the wall between rings solid.

How slow is it? A system call costs a little more than a normal function call, because of the mode switch. That is why libraries often batch work (for example, they buffer file writes) to avoid too many calls.

Not the same as an interrupt. An interrupt comes from hardware at any time. A system call is requested by the program on purpose, at a moment it chooses. They both end in ring 0, but they are different doors.

Windows tip: Process Monitor (Sysinternals, free from Microsoft) shows file, registry and process operations that programs request. Each line is a result of a call going through this very path.

Summary