Understanding NT

In last February’s column, I wrote about a largely undocumented feature of the Windows NT and Windows 2000 registry: symbolic registry links. A symbolic registry link is essentially a registry key that is an alias for some other registry key. For example, the operating system makes HKEY_CURRENT_USER an alias to a key that corresponds to whatever user is currently logged on.

In the February column, I showed how to create your own symbolic registry links, but there were two unfortunate limitations: I didn’t know how to delete or change the value of a symbolic link once the handle to the symbolic link was closed. This effectively made symbolic links only useful in situations where an application could create the symbolic link, use it, and delete it before exiting (to avoid having it become a permanent entry in the registry). With a tip from a reader and a little more poking around, I was able to remove those two limitations, making symbolic registry links a much more useful feature for NT-based versions of Windows. I won’t repeat all the details of the February column here, so you may want to refer back to it for the basics of using symbolic registry links.

Reopening Symbolic Registry Links

Hi Paula,

I find your WDJ February column on registry symbolic links very helpful. It worked very well in my project. I found out more information on opening the symbolic link again and re-assigning the symbolic link. You can call RegOpenKeyEx() with REG_OPTION_OPEN_LINKto re-open the symbolic link key. Then you can query “SymbolicLinkValue” or set “SymbolicLinkValue” to something else. So what you have on page 54, first paragraph, can actually be handled better.

I found this out because I ran into a problem with deleting the symbolic link. I tried your example with one change. Instead of calling RegCreateKeyEx() with REG_OPTION_VOLATILE, I used REG_OPTION_NON_VOLATILE. Everything still works, but now I can’t delete the symbolic link at all. Any advice will be much appreciated.

Thanks, Bill

Thanks, Bill — REG_OPTION_OPEN_LINK is a great find!

I couldn’t find any references to this definition anywhere in the online MSDN documentation, but it is defined in winnt.h. The “REG_OPTION_OPEN” prefix is a good hint that it has something to do with the ulOptions parameter of RegOpenKeyEx(). The “LINK” suffix is a hint that it might have something to do with registry symbolic links.

Using this newly imparted knowledge from Bill, I added some new symbolic link routines to those I presented in February 2001. The updated source code is in symlink.c (Listing 1) and symlink.h (Listing 2). To demonstrate the new routines, I wrote the simple command-line program in main.c (Listing 3). CreateSymLinkKey() and SetSymLink() have not been modified since the February code was published.

OpenSymLink() and ClearSymLink()

OpenSymLink() takes an open key handle (such as HKEY_LOCAL_MACHINE) and the symbolic link sub key name and returns an open handle to the symbolic link key. Recall that attempting to open the key in the normal fashion (without the REG_OPTION_OPEN_LINK option) will open the registry key that the symbolic link points to rather than the symbolic link itself (which is somewhat the point of a symbolic link, isn’t it?). Using REG_OPTION_OPEN_LINK lets you get hold of the link itself.

Once you have a handle to the symbolic link itself, you can also change the key that the symbolic link points to or clear the symbolic link completely. (The key remains, but it no longer points to anything and will thus appear grayed out in regedit.exe and regedt32.exe.) Hence, I also wrote ClearSymLink(). ClearSymLink() takes an open registry key handle to a symbolic link and deletes the special “SymbolicLinkValue” registry value.

Deleting the Symbolic Link Key

As Bill pointed out, the only really interesting problem left is how to delete a registry key that was created as a symbolic link key. Deleting the special “SymbolicLinkValue” will clear the symbolic link, but it does not actually delete the key. Deleting the key using RegDeleteKey() doesn’t work either. If the symbolic link actually points to something, it will delete the key it points to, which is not always what you want. Clearing the symbolic link and then attempting to delete it doesn’t work either. The problem is that the symbolic link key must be opened in a special way (with the REG_OPTION_OPEN_LINK option,) but RegDeleteKey() is designed to do the opening of the key internally. Rather than taking a handle to the key to delete, RegDeleteKey() takes the base key and the name of the key to delete. After fuming about this for a while, it occurred to me to check the ZwXxx() registry routines.

Windows NT/2000 ZwXxx() Routines

The ZwXxx() routines are part of a collection of system services that the Windows NT and Windows 2000 makes available to both user-mode and kernel-mode code. Many, though not all, of these routines start with the prefix “Zw” and are sometimes referred to as the Zw routines. Until recently, only a small subset of these routines were documented by Microsoft in the DDK (Device Driver Kit) documentation.

Last year, Macmillan Technical Publishing released a book by Gary Nebbett entitled Windows NT/2000 Native API Reference. This book contains a description of the 10% or so of the native API routines that are documented in the DDK, as well as a long list of undocumented routines that the author sleuthed himself (with apparently no access to the sources). The level of documentation is similar to that found in the MSDN online sources (the function prototype, a description of the function, each of its parameters, and return values, etc). The book could have benefited from some source code examples, but it’s still a handy reference to have around.

The ZwDeleteKey() Native Service

The ZwDeleteKey() system service routine is documented in the DDK documentation as well as Nebbett’s book. Sure enough, ZwDeleteKey() takes as its only parameter an open handle to the key to delete. Probably one of the trickiest things about calling the native service routines is just getting the code to compile. Most of the native services are defined in ntddk.h or wdm.h. But because ntddk.h and wdm.h contain many of the same definitions as windows.h, you can’t very easily include both files in your code. Nebbett’s book shows an example of using the namespace feature of C++ to place the DDK (ntddk.h or wdm.h) definitions in a different namespace and avoid the reams of redefinition warnings and errors.

Luckily, ZwDeleteKey() takes a single simple parameter of a type defined already in user-mode (HANDLE) and returns a simple type. I was able to easily copy the ZwDeleteKey() function prototype (straight from wdm.h) to my symlink.h file. The HANDLE type is, of course, already defined in windows.h. The only other excerpts from wdm.h that I needed to add were the definitions of NTSYSAPI and NTSTATUS.

Let me reiterate that this example was fairly easy. If you need to call multiple native routines that take parameters of complex data types, it can get out of hand quickly. In that case, including the actual ntddk.h or wdm.h file is a much better choice.

Most, if not all, of the references to the native services are found in the ntdll.lib library included with the DDK. You’ll need to make sure you link with this library if you use the native services.

DeleteSymLink()

This finally brings me back around to my DeleteSymLink() routine. This routine takes an open key and the name of the sub key to delete. As the name implies, I am deleting a symbolic link registry key, so I first open it as such using my OpenSymLink() routine. Then I clear the symbolic link by calling ClearSymLink() to ensure that I don’t delete the key the symbolic link is pointed at. Then I pass the handle returned from OpenSymLink() to ZwDeleteKey(), and the key is summarily deleted.

To demonstrate calling my symbolic link routines, I wrote the simple console application in main.c (Listing 3). main() first creates two keys in the registry (“Software\PaulaT\A” and “Software\PaulaT\B”) and fills in each key with a couple of values. Then I create a symbolic link key under “Software\PaulaT” called “Current” and assign the “Current” symbolic link key to the “Software\PaulaT\A” key. To verify that the “Current” key is really now a symbolic link to the “A” key, I read the values under current; as expected, they correspond to the values under “A”, since my read request of “Current” is actually redirected to “A”.

Then, just to test this month’s new routines, I reopen the symbolic link by calling OpenSymLink() and reset it to the “B” key by calling SetSymLink(). Once again, just to verify it worked correctly, I dump the contents of the two values under the key pointed at by the symbolic link. Then I delete the symbolic link key with my new DeleteSymLink() routine. It’s most effective to step through this routine in a debugger and watch what happens in the registry as you go along.

Once again, I’d like to thank Bill for pointing me in the right direction with the REG_OPTION_OPEN_LINK value. Not only does this solve a nagging problem I had with registry symbolic links, it gives me a good excuse to use one of the ZwXxx() routines.

References

Paula Tomlinson. “Understanding NT,” Windows Developer’s Journal, February 2001.

Paula Tomlinson has been developing Windows, Windows CE, and Windows NT based applications and device drivers for 13 years. In her spare time, Paula enjoys flying N422HJ, a 1951 Ryan Navion. The opinions expressed here are hers alone. Paula can be reached at [email protected].