GetFullPathNameA 함수(fileapi.h)

아티클
06/02/2023

지정된 파일의 전체 경로 및 파일 이름을 검색합니다.

이 작업을 트랜잭션 작업으로 수행하려면 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는 0을 받습니다.

반환 값

함수가 성공하면 반환 값은 종료 null 문자를 포함하지 않고 lpBuffer에 복사된 문자열의 길이(TCHAR)입니다.

lpBuffer 버퍼가 너무 작아서 경로를 포함할 수 없는 경우 반환 값은 경로 및 종료 null 문자를 보유하는 데 필요한 버퍼의 크기(TCHAR)입니다.

다른 이유로 인해 함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

GetFullPathName 은 현재 드라이브 및 디렉터리의 이름을 지정된 파일 이름과 병합하여 지정된 파일의 전체 경로와 파일 이름을 확인합니다. 또한 전체 경로 및 파일 이름의 파일 이름 부분의 주소를 계산합니다.

이 함수는 결과 경로 및 파일 이름이 유효한지 또는 연결된 볼륨에 기존 파일이 표시되는지 확인하지 않습니다.

lpFilePart 매개 변수에는 문자열 버퍼 공간이 필요하지 않지만 단일 주소에 대해서만 충분합니다. 이는 lpBuffer에 대해 이미 존재하는 버퍼 내에서 주소를 반환하기 때문입니다.

공유 및 볼륨 이름은 lpFileName에 유효한 입력입니다. 예를 들어 test-2가 원격 컴퓨터이고 U인 경우 다음 목록은 반환된 경로 및 파일 이름을 ID로 지정합니다. 현재 디렉터리가 볼륨의 루트인 네트워크 매핑 드라이브입니다.

"\\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 함수를 연속 호출하면 현재 디렉터리가 두 호출 간에 변경될 경우 다른 결과를 생성할 수 있다는 점에 유의해야 합니다.

일관되지 않은 결과로 인한 문제를 방지하기 위해 다중 스레드 애플리케이션 및 공유 라이브러리 코드는 상대 경로를 사용하지 않아야 합니다. 상대 경로를 받은 경우 상대 경로를 CreateFile과 같은 함수에 직접 전달하거나 절대 경로로 변환하고 해당 시점의 절대 경로를 사용하여 정확히 한 번 사용해야 합니다.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	Yes
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	Yes
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	예

예제

다음 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을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	fileapi.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll