LNK2019 unresolved external symbol NtOpenFile

Can't let this question go unanswered like this. Because although the remark by Mladen is largely right for this particular native API, the whole topic deserves an in-depth discussion.

Preliminary cautionary note

Up front I should note that in many many cases it is neither desirable nor necessary to use one of the native API functions on Windows. However, there are a few cases where the Win32 API doesn't provide the means to query information or even manipulate data and so on. One such case would be several of the information classes available for NtQueryInformationFile/ZwQueryInformationFile.

One good example is the enumeration of alternate data streams on files and directories, which can be done using the Win32 API, in particular by using the backup APIs, but will require special privileges in that case. Not so if you resort to the native API. The same used to be true for hard links until Windows 2000, which introduced CreateHardLink to the Win32 API. Although in this particular case if you knew your way around you could have used MoveFileEx with MOVEFILE_CREATE_HARDLINK ever since it got introduced (although Microsoft still as of this writing marks it as Reserved for future use ... meh).

The canonical books about the native API are these two:

  • Windows NT/2000 Native API Reference, Gary Nebbett
  • Undocumented Windows 2000 Secrets: A Programmer's Cookbook, Sven B. Schreiber (free version from the author's website here)

... there are more, including one that discusses NT 4 and preceded Nebbett's book. But Nebbett's book used to start the hype around the native API, much like Hoglund's book started the hype around Windows rootkits. Not a reference regarding the Native API topic but still good:

  • Windows Internals, Mark Russinovich et. al.

Check out this website for a huge number of native API functions "documented":

  • http://undocumented.ntinternals.net/

So remember: the inherent risk when using these functions is that they go away in a future Windows version or their semantics change without prior notice. So be careful when you use them, if you use them.

On to glory ...

How to call native API functions

Actually there are two ways to call these functions. Microsoft was forced to disclose some of the native API functions in one of the antitrust law suits some years ago. These were shoved into winternl.h of the SDK. Microsoft expresses it thus:

The NtOpenFile documentation is provided for the sake of full API coverage. NtOpenFile is equivalent to the ZwOpenFile function documented in the DDK. For more information on the ZwOpenFile and related functions, go to http://msdn.microsoft.com/library. In the left-hand pane, click Windows Development, then click Driver Development Kit.

However, there is no accompanying ntdll.lib file in the SDK. Microsoft suggests you link those functions dynamically (second option below).

You have several options:

  1. The most common is to do as you did. But the ntdll.lib import library is only part of the WDKs, not the DDKs.
  2. Use GetProcAddress to find the function pointer and call it. GetModuleHandle is sufficient for the Win32 subsystem since every Win32 program is guaranteed to have loaded ntdll.dll.

Method 1: ntdll.lib

If you have the DDK/WDK - for Driver Development Kit and Windows Driver Kit respectively - you get a full set of ntdll.lib files already. On my system (Windows 7 WDK 7600.16385.1):

C:\WINDDK\7600.16385.1\lib\win7\amd64\ntdll.lib
C:\WINDDK\7600.16385.1\lib\win7\i386\ntdll.lib
C:\WINDDK\7600.16385.1\lib\win7\ia64\ntdll.lib
C:\WINDDK\7600.16385.1\lib\wlh\amd64\ntdll.lib
C:\WINDDK\7600.16385.1\lib\wlh\i386\ntdll.lib
C:\WINDDK\7600.16385.1\lib\wlh\ia64\ntdll.lib
C:\WINDDK\7600.16385.1\lib\wnet\amd64\ntdll.lib
C:\WINDDK\7600.16385.1\lib\wnet\i386\ntdll.lib
C:\WINDDK\7600.16385.1\lib\wnet\ia64\ntdll.lib
C:\WINDDK\7600.16385.1\lib\wxp\i386\ntdll.lib

Create your own makeshift ntdll.lib

Otherwise you have to generate ntdll.lib yourself from the output of dumpbin (or by other means that allow to parse the exports of the DLL) which you can then output into a module definition file from which you can build an export .lib. Sounds convoluted? Not so much, let's see ;)

Using Ero Carrera's pefile Python module, we can do this:

import os, re, sys
from os.path import basename, dirname, join, realpath
try:
    import pefile
except ImportError:
    try:
        sys.path.append(join(realpath(dirname(__file__)), "pefile"))
        import pefile
    except:
        raise

def main(pename):
    from pefile import PE
    print "Parsing %s" % pename
    pe = PE(pename)
    if not getattr(pe, "DIRECTORY_ENTRY_EXPORT", None):
        return "ERROR: given file has no exports."
    modname = basename(pename)
    libname = re.sub(r"(?i)^.*?([^\\/]+)\.(?:dll|exe|sys|ocx)$", r"\1.lib", modname)
    defname = libname.replace(".lib", ".def")
    print "Writing module definition file %s for %s" % (defname, modname)
    with open(defname, "w") as f: # want it to throw, no sophisticated error handling here
        print >>f, "LIBRARY %s\n" % (modname)
        print >>f, "EXPORTS"
        numexp = 0
        for exp in [x for x in pe.DIRECTORY_ENTRY_EXPORT.symbols if x.name]:
            numexp += 1
            print >>f, "\t%s" % (exp.name)
    print "Wrote %s with %d exports" % (defname, numexp)
    print "\n\nUse this to create the export lib:\n\tlib /def:%s /out:%s" % (defname, libname)

if __name__ == '__main__':
    if len(sys.argv) != 2:
        sys.exit("ERROR:\n\tSyntax: fakelib <dllfile>\n")
    sys.exit(main(sys.argv[1]))

A sample output of running this script (when named fakelib.py) would be:

> fakelib.py ntdll.dll
Parsing ntdll.dll
Writing module definition file ntdll.def for ntdll.dll
Wrote ntdll.def with 1984 exports


Use this to create the export lib:
        lib /def:ntdll.def /out:ntdll.lib

Then we run the command as given on the last line. It is even better to give the /machine: parameter, of course. This is left as an "exercise" (*cough* *cough*) to the reader. The output with VS 2012 will be:

> lib /def:ntdll.def /out:ntdll.lib
Microsoft (R) Library Manager Version 11.00.51106.1
Copyright (C) Microsoft Corporation.  All rights reserved.

LINK : warning LNK4068: /MACHINE not specified; defaulting to X86
   Creating library ntdll.lib and object ntdll.exp

Congratulations. You can now use the ntdll.lib created by Microsoft's own lib.exe to statically import from ntdll.dll, even without having the "real" (original) .lib on your system.

Adjust the path and file names to your needs and tastes.

When using MinGW

Damon pointed out in a comment that the toolchain included with MinGW contains a tool gendef that can do the job of above Python script and that the output can be fed to dlltool.

Issues

The above method works perfectly when targeting x64 (64-bit), but for x86 (32-bit) I have encountered linker errors at times.

The issue is that the name decoration for __stdcall differs between x64 and x86. The former doesn't really use the same __stdcall as x86 and therefore just prepends an underscore. However, the latter also appends a the number of arguments times sizeof(void*) (i.e. 4). So for one argument the decorated function name for a function int __stdcall foo(int); becomes _foo@4.

This KB article from Microsoft outlines a way to get around the issue.

Method 2: dynamically imported, using GetProcAddress

Documentation in MSDN states (for NtOpenFile):

Note that the DDK header file Ntdef.h is necessary for many constant definitions as well as the InitializeObjectAttributes macro. The associated import library, Ntdll.lib is also available in the DDK. You can also use the LoadLibrary and GetProcAddress functions to dynamically link to Ntdll.dll.

Declare a function type, e.g. here we declare the type TFNNtOpenFile suitable in your case:

typedef NTSTATUS (NTAPI  *TFNNtOpenFile)(
  OUT PHANDLE FileHandle,
  IN ACCESS_MASK DesiredAccess,
  IN POBJECT_ATTRIBUTES ObjectAttributes,
  OUT PIO_STATUS_BLOCK IoStatusBlock,
  IN ULONG ShareAccess,
  IN ULONG OpenOptions
);

... and then retrieve the function pointer and call it:

TFNNtOpenFile pfnNtOpenFile = (TFNNtOpenFile)GetProcAddress(GetModuleHandle("ntdll.dll"), "NtOpenFile");
status = pfnNtOpenFile(...); // can't be bothered to type out all parameters ;)

an alternative way of retrieving the function pointer could be this one:

static NTSTATUS (NTAPI  *NtOpenFile)(
  OUT PHANDLE,
  IN ACCESS_MASK,
  IN POBJECT_ATTRIBUTES,
  OUT PIO_STATUS_BLOCK,
  IN ULONG,
  IN ULONG
);
(FARPROC)&NtOpenFile = GetProcAddress(GetModuleHandle("ntdll.dll"), "NtOpenFile");

which could be condensed even further by using the preprocessor stringification operator (#). The choice is yours.


These functions cannot be called directly because they belong to internal API and are not exposed through any of the libraries. You need to obtain addresses of these function using GetProcAddress.

For more information look here.

Tags:

C++

Winapi

Visual C++

Linker Errors

Recent Posts