Broken and Ill-Documented API for Windows Mount-Points

 

This note is written for programmers who must deal with mount points under Windows. It applies to Windows Vista Home Premium version 6.0.6000 with kernel32.dll version 6.0.6000.16386. It may apply to other versions of Microsoft’s operating systems, but I have no first-hand knowledge of such. If you are having trouble with GetVolumePathNamesForVolumeName, or other functions to manage links and junctions, the following may apply.

With reference to:

 http://blog.kalmbach-software.de/2008/02/28/howto-correctly-read-reparse-data-in-vista/

 http://blogs.msdn.com/adioltean/archive/2005/04/16/408947.aspx

 http://msdn.microsoft.com/en-us/library/aa365730(VS.85).aspx

 http://msdn.microsoft.com/en-us/library/aa365503(VS.85).aspx

Programmers who must manage links under Windows Vista should beware!  Of the several low-level functions which purport to manage links and junctions under Vista, it appears that at least two are completely broken and others will exhibit unexpected behavior depending on factors outside of your control.

The broken functions are GetVolumePathNamesForVolumeNameA and GetVolumePathNamesForVolumeNameW.

After extensive thrashing, I have come to the conclusion that these functions do not operate as
documented (see http://msdn.microsoft.com/en-us/library/aa364998(VS.85).aspx); indeed, I can not get these functions to work at all.  Both return 0 (BOOL FALSE) for all combinations of arguments applied as per the Microsoft documentation.

In addition to the broken functionality, unexpected behavior arises from the different facilities for creating mount points (variously called Junctions, Directory Junctions, Mount Points, and/or Volume Mount Points in Microsoft’s documentation) under Vista 6.0.6000.  These facilities are: mountvol, mklink, and /Control Panel/System and Maintenance/Administrative Tools/Computer Management/Storage/Disk Management/.   Mountvol and Disk Management function similarly; mklink is different.

When you create a mount point using mountvol or Disk Management, the substitute name in the REPARSE_DATA_BUFFER (see http://msdn.microsoft.com/en-us/library/ms791514.aspx) acquired via DeviceIoControl associated with the mount point is a low-level volume designator of the form \??\Volume{GUID}\.  When you create a mount point using mklink (e.g. via mklink /J MOUNTPATH X:), the substitute name in the REPARSE_DATA_BUFFER is a disk-name (X:), not a volume designator.  In neither case is the print-name field of the REPARSE_DATA_BUFFER populated. 

[Note that, until very recently the Microsoft documentation for REPARSE_DATA_BUFFER incorrectly omitted the flags field from the SymbolicLinkReparseBuffer part of the union.]

[For a description of how to acquire the REPARSE_DATA_BUFFER in C++ for Windows links, see  http://blog.kalmbach-software.de/2008/02/28/howto-correctly-read-reparse-data-in-vista/.]

Note also that mountvol displays volume designators with the syntax \\?\Volume{GUID}\ whereas the REPARSE_DATA_BUFFER returns volume designators with the syntax \??\Volume{GUID}\.  The functions GetVolumeNameForVolumeMountPointA and GetVolumeNameForVolumeMountPointW return volume designators with the syntax \\?\Volume{GUID}\.

What this means is that in order to acquire the actual disk name from a mount point you will need to examine the substitute name acquired in the REPARSE_DATA_BUFFER.  If the name is of the form \??\X:\ you are done.  If it is of the form \??\Volume{GUID}\, you will need to examine the 26 possible results from GetVolumeNameForVolumeMountPoint (one for each disk name of the form X:\).  If there is a match in the GUID’s, then you have found the actual disk to which the mount point refers.

I am sure this all makes sense to Microsoft somehow.  It doesn’t to me; but, hey.

I’ve implemented all this in Steel Bank Common Lisp’s FFI in order to fix the truename function under Windows.  You are welcome to look at the code for inspiration, but if you are a C/C++/C#/Java/etc. hacker it will probably be illegible.