GetFullPathNameA 関数 (fileapi.h)

[アーティクル]
03/13/2024

指定したファイルの最終パスとファイル名を取得します。

この操作をトランザクション操作として実行するには、 GetFullPathNameTransacted 関数を使用します。

ファイル名とパス名の詳細については、「ファイル名、パス、および名前空間」を参照してください。

メモマルチスレッドアプリケーションまたは共有ライブラリコードでの GetFullPathName 関数での相対パスの使用については、「解説」セクションを参照してください。

構文

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

パラメーター

[in] lpFileName

ファイルの名前です。

このパラメーターには、短い (8.3 形式) または長いファイル名を指定できます。この文字列には、共有名またはボリューム名を指定することもできます。

[in] nBufferLength

ドライブとパスの null で終わる文字列を受信するバッファーのサイズ (TCHAR)。

[out] lpBuffer

ドライブとパスの null で終わる文字列を受け取るバッファーへのポインター。

[out] lpFilePart

パス内の最終的なファイル名コンポーネントのアドレス ( lpBuffer 内) を受け取るバッファーへのポインター。

このパラメーターは、NULL でもかまいません。

lpBuffer がファイルではなくディレクトリを参照している場合、lpFilePart は 0 を受け取ります。

戻り値

関数が成功した場合、戻り値は lpBuffer にコピーされた文字列の TCHAR の長さであり、終端の null 文字は含まれません。

lpBuffer バッファーが小さすぎてパスを格納できない場合、戻り値は、パスと終端の null 文字を保持するために必要なバッファーのサイズ (TCHAR) です。

関数が他の理由で失敗した場合、戻り値は 0 になります。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

GetFullPathName は、現在のドライブとディレクトリの名前を指定したファイル名とマージして、指定したファイルの完全なパスとファイル名を決定します。また、完全パスとファイル名のファイル名部分のアドレスも計算されます。

この関数は、結果のパスとファイル名が有効であること、または関連付けられているボリューム上に既存のファイルが表示されることを確認しません。

lpFilePart パラメーターには文字列バッファー領域は必要ありませんが、1 つのアドレスに対してのみ十分であることに注意してください。これは、 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 で指定された値以上の場合は、パスを保持するのに十分な大きさのバッファーを使用して関数を再度呼び出すことができます。この場合の例は、動的割り当てに長さ 0 のバッファーを使用するだけでなく、コード例に関するセクションを参照してください。

メモこの場合の戻り値は終端の null 文字を含む長さですが、成功した場合の戻り値には、カウントに終端の null 文字は含まれません。

GetFullPathName 関数に渡される相対パスは、プロセスの現在のディレクトリに対する相対パスとして解釈されます。 SetCurrentDirectory 関数によって書き込まれた現在のディレクトリの状態は、プロセスに対してグローバルであり、いつでも任意のスレッドで変更できます。相対パスを使用して GetFullPathName 関数を連続して呼び出すと、現在のディレクトリが 2 つの呼び出しの間で変更された場合、異なる結果が生成される可能性があることに注意する必要があります。

一貫性のない結果が原因で発生する問題を回避するには、マルチスレッドアプリケーションと共有ライブラリコードで相対パスを使用しないようにする必要があります。相対パスを受け取る場合は、相対パスを CreateFile などの関数に直接渡すか、絶対パスに変換し、そのポイントの絶対パスを使用して、1 回だけ使用する必要があります。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ	サポートされています
サーバーメッセージブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 Transparent Failover (TFO)	はい
スケールアウトファイル共有 (SO) を使う SMB 3.0	はい
クラスターの共有ボリュームファイルシステム (CsvFS)	はい
Resilient File System (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 を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

次の方法で共有

GetFullPathNameA 関数 (fileapi.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

その他のリソース