GetFullPathNameA 함수(fileapi.h)

아티클
11/20/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 0을 받습니다.

반환 값

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

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

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

발언

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

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

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

공유 및 볼륨 이름은 lpFileName유효한 입력입니다. 예를 들어 test-2가 원격 컴퓨터이고 U인 경우 다음 목록 ID는 반환된 경로 및 파일 이름을 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 프로토콜	예
SMB 3.0 TFO(투명한 장애 조치(failover)	예
SO(스케일 아웃 파일 공유)가 있는 SMB 3.0	예
CsvFS(클러스터 공유 볼륨 파일 시스템)	예
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을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한 규칙을 참조하세요.

요구 사항

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

참고 항목

파일 관리 함수

getFullPathNameTransacted

GetLongPathName

GetShortPathName

GetTempPath

SearchPath

다음을 통해 공유

GetFullPathNameA 함수(fileapi.h)

통사론

매개 변수

반환 값

발언

예제

요구 사항

참고 항목

피드백

추가 리소스