GetFullPathNameA 函式 (fileapi.h)

發行項
03/05/2024

擷取指定檔案的完整路徑和檔名。

若要以交易作業的形式執行此作業，請使用 GetFullPathNameTransacted 函式。

如需檔案和路徑名稱的詳細資訊，請參閱檔名、路徑和命名空間。

注意如需在多線程應用程式或共用連結庫程序代碼中搭配 GetFullPathName 函式使用相對路徑的討論，請參閱一節。

語法

DWORD GetFullPathNameA(
  [in]  LPCSTR lpFileName,
  [in]  DWORD  nBufferLength,
  [out] LPSTR  lpBuffer,
  [out] LPSTR  *lpFilePart
);

參數

[in] lpFileName

檔案的名稱。

此參數可以是簡短 (8.3 窗體) 或長檔名。此字串也可以是共用或磁碟區名稱。

[in] nBufferLength

要接收 TCHAR 中磁碟驅動器和路徑之 Null 終止字串的緩衝區大小。

[out] lpBuffer

緩衝區的指標，接收磁碟驅動器和路徑的 Null 終止字串。

[out] lpFilePart

緩衝區的指標，在路徑中最後檔名元件的 lpBuffer) 內接收位址 (。

此參數可以是 Null。

如果 lpBuffer 參考目錄而非檔案， lpFilePart 會收到零。

傳回值

如果函式成功，傳回值會是複製到 lpBuffer 之字串的長度，不包括終止 Null 字元。

如果 lpBuffer 緩衝區太小而無法包含路徑，則傳回值會是保留路徑和終止 Null 字元所需的緩衝區大小。

如果函式因任何其他原因而失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

GetFullPathName 會將目前磁碟驅動器和目錄的名稱與指定的檔名合併，以判斷指定檔案的完整路徑和檔名。它也會計算完整路徑和檔名之檔名部分的位址。

此函式不會驗證產生的路徑和檔名是否有效，或看到相關聯磁碟區上的現有檔案。

請注意， lpFilePart 參數不需要字串緩衝區空間，但只能用於單一位址。這是因為它只會傳回已存在 lpBuffer 之緩衝區內的位址。

共用和磁碟區名稱是 lpFileName 的有效輸入。例如，如果 test-2 是遠端電腦且 U：是目前目錄為磁碟區根目錄的網路對應磁碟驅動器，下列清單會識別傳回的路徑和檔名：

如果您指定 “\\test-2\q$\lh” 傳回的路徑為 “\\test-2\q$\lh”
如果您指定 “\\？\UNC\test-2\q$\lh” 傳回的路徑為 “\\？\UNC\test-2\q$\lh”
如果您指定 “U：” 傳回的路徑是 “U：\” 磁碟驅動器上的目前目錄

GetFullPathName 不會轉換指定的檔名 lpFileName。如果指定的檔名存在，您可以使用 GetLongPathName 或 GetShortPathName 分別轉換成長或短路徑名稱。

如果傳回值大於或等於 nBufferLength 中指定的值，您可以使用足以保存路徑的緩衝區再次呼叫函式。如需此案例的範例，除了使用零長度緩衝區進行動態配置之外，請參閱範例程式代碼一節。

注意雖然此案例中的傳回值是包含終止 Null 字元的長度，但成功時的傳回值不包含計數中的終止 Null 字元。

傳遞至 GetFullPathName 函式的相對路徑會解譯為相對於進程的目前目錄。 SetCurrentDirectory 函式所寫入的目前目錄狀態是進程的全域狀態，而且可以隨時由任何線程變更。如果目前目錄在兩個呼叫之間變更，應用程式應該注意，如果對具有相對路徑的 GetFullPathName 函式進行連續呼叫，可能會產生不同的結果。

為了避免結果不一致所造成的問題，多線程應用程式和共用連結庫程式碼應該避免使用相對路徑。如果收到相對路徑，則應該只取用一次，方法是將相對路徑直接傳遞至 CreateFile 之類的函式，或將它轉換成絕對路徑，並使用該點正向的絕對路徑。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。

技術	支援
伺服器消息塊 (SMB) 3.0 通訊協定	Yes
SMB 3.0 透明故障轉移 (TFO)	Yes
具有向外延展檔案共用的SMB 3.0 (SO)	Yes
叢集共用磁碟區文件系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	是

範例

下列 C++ 範例顯示 GetFullPathName、 GetLongPathName 和 GetShortPathName 的基本用法。如需使用動態配置的另一個範例，請參閱 GetShortPathName。

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

#define BUFSIZE 4096
#define LONG_DIR_NAME TEXT("c:\\longdirectoryname")

void _tmain(int argc, TCHAR *argv[])
{
    DWORD  retval=0;
    BOOL   success; 
    TCHAR  buffer[BUFSIZE]=TEXT(""); 
    TCHAR  buf[BUFSIZE]=TEXT(""); 
    TCHAR** lppPart={NULL};

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [file]\n"), argv[0]);
      return;
   }

// Retrieve the full path name for a file. 
// The file does not need to exist.

    retval = GetFullPathName(argv[1],
                 BUFSIZE,
                 buffer,
                 lppPart);
    
    if (retval == 0) 
    {
        // Handle an error condition.
        printf ("GetFullPathName failed (%d)\n", GetLastError());
        return;
    }
    else 
    {
        _tprintf(TEXT("The full path name is:  %s\n"), buffer);
        if (lppPart != NULL && *lppPart != 0)
        {
            _tprintf(TEXT("The final component in the path name is:  %s\n"), *lppPart);
        }
    }


// Create a long directory name for use with the next two examples.

    success = CreateDirectory(LONG_DIR_NAME,
                              NULL);

    if (!success)
    {
        // Handle an error condition.
        printf ("CreateDirectory failed (%d)\n", GetLastError());
        return;
    }


// Retrieve the short path name.  

    retval = GetShortPathName(LONG_DIR_NAME,
                  buf,
                  BUFSIZE);

    if (retval == 0) 
    {
        // Handle an error condition.
         printf ("GetShortPathName failed (%d)\n", GetLastError());
         return;
    }
    else _tprintf(TEXT("The short name for %s is %s\n"), 
                  LONG_DIR_NAME, buf);


// Retrieve the long path name.  

    retval = GetLongPathName(buf,
              buffer,
              BUFSIZE);

    if (retval == 0) 
    {
        // Handle an error condition.
         printf ("GetLongPathName failed (%d)\n", GetLastError());
         return;
    }
    else _tprintf(TEXT("The long name for %s is %s\n"), buf, buffer);

// Clean up the directory.

    success = RemoveDirectory(LONG_DIR_NAME);
    if (!success)
    {
        // Handle an error condition.
        printf ("RemoveDirectory failed (%d)\n", GetLastError());
        return;
    }
}

注意

fileapi.h 標頭會將 GetFullPathName 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	fileapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll