Retrieves the volume mount point where the specified path is mounted.
BOOL GetVolumePathNameW( LPCWSTR lpszFileName, LPWSTR lpszVolumePathName, DWORD cchBufferLength );
A pointer to the input path string. Both absolute and relative file and directory names, for example "..", are acceptable in this path.
If you specify a relative directory or file name without a volume qualifier, GetVolumePathName returns the drive letter of the boot volume.
If this parameter is an empty string, "", the function fails but the last error is set to ERROR_SUCCESS.
A pointer to a string that receives the volume mount point for the input path.
The length of the output buffer, in TCHARs.
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If a specified path is passed, GetVolumePathName returns the path to the volume mount point, which means that it returns the root of the volume where the end point of the specified path is located.
For example, assume that you have volume D mounted at C:\Mnt\Ddrive and volume E mounted at "C:\Mnt\Ddrive\Mnt\Edrive". Also assume that you have a file with the path "E:\Dir\Subdir\MyFile". If you pass "C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile" to GetVolumePathName, it returns the path "C:\Mnt\Ddrive\Mnt\Edrive".
If either a relative directory or a file is passed without a volume qualifier, the function returns the drive letter of the boot volume. The drive letter of the boot volume is also returned if an invalid file or directory name is specified without a valid volume qualifier. If a valid volume specifier is given, and the volume exists, but an invalid file or directory name is specified, the function will succeed and that volume name will be returned. For examples, see the Examples section of this topic.
You must specify a valid Win32 namespace path. If you specify an NT namespace path, for example, "\DosDevices\H:" or "\Device\HardDiskVolume6", the function returns the drive letter of the boot volume, not the drive letter of that NT namespace path.
For more information about path names and namespaces, see Naming Files, Paths, and Namespaces.
You can specify both local and remote paths. If you specify a local path, GetVolumePathName returns a full path whose prefix is the longest prefix that represents a volume.
If a network share is specified, GetVolumePathName returns the shortest path for which GetDriveType returns DRIVE_REMOTE, which means that the path is validated as a remote drive that exists, which the current user can access.
There are certain special cases that do not return a trailing backslash. These occur when the output buffer length is one character too short. For example, if lpszFileName is C: and lpszVolumePathName is 4 characters long, the value returned is "C:"; however, if lpszVolumePathName is 3 characters long, the value returned is "C:". A safer but slower way to set the size of the return buffer is to call the GetFullPathName function, and then make sure that the buffer size is at least the same size as the full path that GetFullPathName returns. If the output buffer is more than one character too short, the function will fail and return an error.
In Windows 8 and Windows Server 2012, this function is supported by the following technologies.
|Server Message Block (SMB) 3.0 protocol||No|
|SMB 3.0 Transparent Failover (TFO)||No|
|SMB 3.0 with Scale-out File Shares (SO)||No|
|Cluster Shared Volume File System (CsvFS)||Yes|
|Resilient File System (ReFS)||Yes|
SMB does not support volume management functions.
- The path is not formed correctly.
- The path does not exist.
- The current user does not have access to the path.
W:\Adiris a junction point that points to
C:\Adir, then GetVolumePathName invoked on
C:\". If the specified path traverses multiple junction points, the entire chain is followed, and GetVolumePathName returns the volume to which the last junction point in the chain refers.
If a remote path to a mounted folder or junction point is specified, the path is parsed as a remote path, and
the mounted folder or junction point are ignored. For example if
For the following set of examples, U: is mapped to the remote computer
\YourComputer\C$, and Q is a local drive.
C:\Dir_C is linked to
C: is mapped to
X: on a remote computer, calling
GetVolumePathName and specifying
X:\Dir_C on the remote computer returns
FALSE with error 123 because a specified remote path was not valid;
W$ share does not exist or no user access granted.
C:\COM2 (which exists)
FALSE with error 123 because a non-existent COM device was specified.
G:\invalid (invalid path)
\\.\I:\aaa\invalid (invalid path)
\\YourComputer\C$\invalid (invalid trailing path
Minimum supported client
Windows XP [desktop apps only]
Minimum supported server
Windows Server 2003 [desktop apps only]
fileapi.h (include Windows.h)
For the following set of examples, U: is mapped to the remote computer \YourComputer\C$, and Q is a local drive.