ホーム › Storage.FileSystem › GetFullPathNameA

GetFullPathNameA

関数

相対パスを絶対パスに変換して取得する(ANSI版)。

DLLKERNEL32.dll文字セットANSI (-A)呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

DWORD GetFullPathNameA(
    LPCSTR lpFileName,
    DWORD nBufferLength,
    LPSTR lpBuffer,   // optional
    LPSTR* lpFilePart   // optional
);

パラメーター

名前	型	方向	説明
lpFileName	LPCSTR	in	ファイルの名前。このパラメーターには、短い形式 (8.3 形式) または長いファイル名を指定できます。この文字列には、共有名またはボリューム名を指定することもできます。
nBufferLength	DWORD	in	ドライブとパスの null 終端文字列を受け取るバッファーのサイズ (TCHAR 単位)。
lpBuffer	LPSTR	outoptional	ドライブとパスの null 終端文字列を受け取るバッファーへのポインター。
lpFilePart	LPSTR*	outoptional	パス内の最後のファイル名コンポーネントのアドレス (lpBuffer 内) を受け取るバッファーへのポインター。このパラメーターには NULL を指定できます。 lpBuffer がファイルではなくディレクトリを指している場合、lpFilePart はゼロを受け取ります。

戻り値の型: DWORD

公式ドキュメント

指定したファイルのフルパスとファイル名を取得します。(ANSI)

戻り値

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

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

それ以外の理由で関数が失敗した場合、戻り値はゼロです。拡張エラー情報を取得するには、GetLastError を呼び出します。

解説(Remarks)

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 で指定した値以上である場合、パスを保持するのに十分な大きさのバッファーを用意して関数を再度呼び出すことができます。このケースの例、および動的割り当てのためにゼロ長バッファーを使用する例については、「Example Code」セクションを参照してください。

注意このケースでの戻り値は終端の null 文字を含む長さですが、成功時の戻り値はカウントに終端の null 文字を含みません。

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

一貫性のない結果に起因する問題を回避するため、マルチスレッドアプリケーションおよび共有ライブラリのコードでは相対パスの使用を避けるべきです。相対パスを受け取った場合は、相対パスを CreateFile のような関数に直接渡すか、絶対パスに変換してそれ以降は絶対パスを使用するかのいずれかにより、ちょうど 1 回だけ消費すべきです。

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

テクノロジ	サポート
Server Message Block (SMB) 3.0 プロトコル	はい
SMB 3.0 トランスペアレントフェールオーバー (TFO)	はい
SMB 3.0 とスケールアウトファイル共有 (SO)	はい
クラスター共有ボリュームファイルシステム (CsvFS)	はい
回復性のあるファイルシステム (ReFS)	はい

Examples

次の 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 版を自動的に選択するエイリアスとして定義します。エンコーディング中立のエイリアスの使用を、エンコーディング中立でないコードと混在させると、コンパイルエラーまたはランタイムエラーを引き起こす不一致が生じる可能性があります。詳細については、Conventions for Function Prototypes を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

DWORD GetFullPathNameA(
    LPCSTR lpFileName,
    DWORD nBufferLength,
    LPSTR lpBuffer,   // optional
    LPSTR* lpFilePart   // optional
);

[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern uint GetFullPathNameA(
    [MarshalAs(UnmanagedType.LPStr)] string lpFileName,   // LPCSTR
    uint nBufferLength,   // DWORD
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder lpBuffer,   // LPSTR optional, out
    IntPtr lpFilePart   // LPSTR* optional, out
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function GetFullPathNameA(
    <MarshalAs(UnmanagedType.LPStr)> lpFileName As String,   ' LPCSTR
    nBufferLength As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPStr)> lpBuffer As System.Text.StringBuilder,   ' LPSTR optional, out
    lpFilePart As IntPtr   ' LPSTR* optional, out
) As UInteger
End Function

' lpFileName : LPCSTR
' nBufferLength : DWORD
' lpBuffer : LPSTR optional, out
' lpFilePart : LPSTR* optional, out
Declare PtrSafe Function GetFullPathNameA Lib "kernel32" ( _
    ByVal lpFileName As String, _
    ByVal nBufferLength As Long, _
    ByVal lpBuffer As String, _
    ByVal lpFilePart As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetFullPathNameA = ctypes.windll.kernel32.GetFullPathNameA
GetFullPathNameA.restype = wintypes.DWORD
GetFullPathNameA.argtypes = [
    wintypes.LPCSTR,  # lpFileName : LPCSTR
    wintypes.DWORD,  # nBufferLength : DWORD
    wintypes.LPSTR,  # lpBuffer : LPSTR optional, out
    ctypes.c_void_p,  # lpFilePart : LPSTR* optional, out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
GetFullPathNameA = Fiddle::Function.new(
  lib['GetFullPathNameA'],
  [
    Fiddle::TYPE_VOIDP,  # lpFileName : LPCSTR
    -Fiddle::TYPE_INT,  # nBufferLength : DWORD
    Fiddle::TYPE_VOIDP,  # lpBuffer : LPSTR optional, out
    Fiddle::TYPE_VOIDP,  # lpFilePart : LPSTR* optional, out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "kernel32")]
extern "system" {
    fn GetFullPathNameA(
        lpFileName: *const u8,  // LPCSTR
        nBufferLength: u32,  // DWORD
        lpBuffer: *mut u8,  // LPSTR optional, out
        lpFilePart: *mut *mut u8  // LPSTR* optional, out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern uint GetFullPathNameA([MarshalAs(UnmanagedType.LPStr)] string lpFileName, uint nBufferLength, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder lpBuffer, IntPtr lpFilePart);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_GetFullPathNameA' -Namespace Win32 -PassThru
# $api::GetFullPathNameA(lpFileName, nBufferLength, lpBuffer, lpFilePart)

#uselib "KERNEL32.dll"
#func global GetFullPathNameA "GetFullPathNameA" sptr, sptr, sptr, sptr
; GetFullPathNameA lpFileName, nBufferLength, varptr(lpBuffer), varptr(lpFilePart)   ; 戻り値は stat
; lpFileName : LPCSTR -> "sptr"
; nBufferLength : DWORD -> "sptr"
; lpBuffer : LPSTR optional, out -> "sptr"
; lpFilePart : LPSTR* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global GetFullPathNameA "GetFullPathNameA" str, int, var, var
; res = GetFullPathNameA(lpFileName, nBufferLength, lpBuffer, lpFilePart)
; lpFileName : LPCSTR -> "str"
; nBufferLength : DWORD -> "int"
; lpBuffer : LPSTR optional, out -> "var"
; lpFilePart : LPSTR* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global GetFullPathNameA "GetFullPathNameA" str, int, sptr, sptr
; res = GetFullPathNameA(lpFileName, nBufferLength, varptr(lpBuffer), varptr(lpFilePart))
; lpFileName : LPCSTR -> "str"
; nBufferLength : DWORD -> "int"
; lpBuffer : LPSTR optional, out -> "sptr"
; lpFilePart : LPSTR* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。