Retrieves the final path for the specified file.

For more information about file and path names, seeNaming a File.

Syntax

DWORD GetFinalPathNameByHandleA(  [in]  HANDLE hFile,  [out] LPSTR  lpszFilePath,  [in]  DWORD  cchFilePath,  [in]  DWORD  dwFlags);

Parameters

[in] hFile

A handle to a file or directory.

[out] lpszFilePath

A pointer to a buffer that receives the path ofhFile.

[in] cchFilePath

The size oflpszFilePath, inTCHARs. This value must include aNULL termination character.

[in] dwFlags

The type of result to return. This parameter can be one of the following values.

This parameter can also include one of the following values.

Return value

If the function succeeds, the return value is the length of the string received bylpszFilePath, inTCHARs. This value does not include thesize of the terminating null character.

Windows Server 2008 and Windows Vista:  For the ANSI version of this function,GetFinalPathNameByHandleA, the return valueincludes the size of the terminating null character.

If the function fails becauselpszFilePath is too small to hold the string plus theterminating null character, the return value is the required buffer size, inTCHARs. 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, callGetLastError.

Remarks

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 linknamed "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, seeCreateFile.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Examples

The following example demonstrates the use of theGetFinalPathNameByHandle function.

#include <windows.h>#include <tchar.h>#include <stdio.h>#define BUFSIZE MAX_PATHvoid __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);}

Requirements

See also

File Management Functions