| UID | title | description | helpviewer_keywords | old-location | tech.root | ms.assetid | ms.date | ms.keywords | req.header | req.include-header | req.target-type | req.target-min-winverclnt | req.target-min-winversvr | req.kmdf-ver | req.umdf-ver | req.ddi-compliance | req.unicode-ansi | req.idl | req.max-support | req.namespace | req.assembly | req.type-library | req.lib | req.dll | req.irql | targetos | req.typenames | req.redist | ms.custom | f1_keywords | dev_langs | topic_type | api_type | api_location | api_name | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
NF:fileapi.GetFinalPathNameByHandleA |
GetFinalPathNameByHandleA function (fileapi.h) |
Retrieves the final path for the specified file. (ANSI) |
|
fs\getfinalpathnamebyhandle.htm |
fs |
02783ba9-a8d7-482f-a8b1-7cac934cf476 |
12/05/2018 |
FILE_NAME_NORMALIZED, FILE_NAME_OPENED, GetFinalPathNameByHandle, GetFinalPathNameByHandle function [Files], GetFinalPathNameByHandleA, GetFinalPathNameByHandleW, VOLUME_NAME_DOS, VOLUME_NAME_GUID, VOLUME_NAME_NONE, VOLUME_NAME_NT, fileapi/GetFinalPathNameByHandle, fileapi/GetFinalPathNameByHandleA, fileapi/GetFinalPathNameByHandleW, fs.getfinalpathnamebyhandle, fs.getfinalpathnamebyhandlew, winbase/GetFinalPathNameByHandle, winbase/GetFinalPathNameByHandleA, winbase/GetFinalPathNameByHandleW |
fileapi.h |
Windows.h |
Windows |
Windows Vista [desktop apps \| UWP apps] |
Windows Server 2008 [desktop apps \| UWP apps] |
GetFinalPathNameByHandleW (Unicode) and GetFinalPathNameByHandleA (ANSI) |
Kernel32.lib |
Kernel32.dll |
Windows |
19H1 |
|
|
|
|
|
|
Retrieves the final path for the specified file.
For more information about file and path names, see Naming a File.
A handle to a file or directory.
A pointer to a buffer that receives the path of hFile.
The size of lpszFilePath, in TCHARs. This value must include a NULL termination character.
The type of result to return. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
|
Return the normalized drive name. This is the default. |
|
Return the opened file name (not normalized). |
This parameter can also include one of the following values.
If the function succeeds, the return value is the length of the string received by lpszFilePath, in TCHARs. This value does not include the size of the terminating null character.
Windows Server 2008 and Windows Vista: For the ANSI version of this function, GetFinalPathNameByHandleA, the return value includes the size of the terminating null character.
If the function fails because lpszFilePath is too small to hold the string plus the terminating null character, the return value is the required buffer size, in TCHARs. This value includes the size of the terminating null character.
If the function fails for any other reason, the return value is zero. To get extended error information, call GetLastError.
| Return code | Description |
|---|---|
|
Can be returned if you are searching for a drive letter and one does not exist. For example, the handle
was opened on a drive that is not currently mounted, or if you create a volume and do not assign it a drive
letter. If a volume has no drive letter, you can use the volume GUID path to
identify it.
This return value can also be returned if you are searching for a volume GUID path on a network share. Volume GUID paths are not created for network shares. |
|
Insufficient memory to complete the operation. |
|
Invalid flags were specified for dwFlags. |
The Server Message Block (SMB) Protocol does not support queries for normalized paths. Consequently, when you call this function passing the handle of a file opened using SMB, and with the FILE_NAME_NORMALIZED flag, the function splits the path into its components and tries to query for the normalized name of each of those components in turn. If the user lacks access permission to any one of those components, then the function call fails with ERROR_ACCESS_DENIED.
A final path is the path that is returned when a path is fully resolved. For example, for a symbolic link named "C:\tmp\mydir" that points to "D:\yourdir", the final path would be "D:\yourdir".
The string that is returned by this function uses the "\\?\" syntax. For more information, see CreateFile.
In Windows 8 and Windows Server 2012, this function is supported by the following technologies.
| Technology | Supported |
|---|---|
| Server Message Block (SMB) 3.0 protocol | Yes |
| SMB 3.0 Transparent Failover (TFO) | Yes |
| SMB 3.0 with Scale-out File Shares (SO) | Yes |
| Cluster Shared Volume File System (CsvFS) | Yes |
| Resilient File System (ReFS) | Yes |
The following example demonstrates the use of the GetFinalPathNameByHandle function.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE MAX_PATH
void __cdecl _tmain(int argc, TCHAR *argv[])
{
TCHAR Path[BUFSIZE];
HANDLE hFile;
DWORD dwRet;
printf("\n");
if( argc != 2 )
{
printf("ERROR:\tIncorrect number of arguments\n\n");
printf("%s <file_name>\n", argv[0]);
return;
}
hFile = CreateFile(argv[1], // file to open
GENERIC_READ, // open for reading
FILE_SHARE_READ, // share for reading
NULL, // default security
OPEN_EXISTING, // existing file only
FILE_ATTRIBUTE_NORMAL, // normal file
NULL); // no attr. template
if( hFile == INVALID_HANDLE_VALUE)
{
printf("Could not open file (error %d\n)", GetLastError());
return;
}
dwRet = GetFinalPathNameByHandle( hFile, Path, BUFSIZE, VOLUME_NAME_NT );
if(dwRet < BUFSIZE)
{
_tprintf(TEXT("\nThe final path is: %s\n"), Path);
}
else printf("\nThe required buffer size is %d.\n", dwRet);
CloseHandle(hFile);
}
Note
The fileapi.h header defines GetFinalPathNameByHandle as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.