SetFilePointerEx 함수(fileapi.h)

아티클
02/01/2024

지정된 파일의 파일 포인터를 이동합니다.

구문

BOOL SetFilePointerEx(
  [in]            HANDLE         hFile,
  [in]            LARGE_INTEGER  liDistanceToMove,
  [out, optional] PLARGE_INTEGER lpNewFilePointer,
  [in]            DWORD          dwMoveMethod
);

매개 변수

[in] hFile

파일에 대한 핸들입니다. 파일 핸들은 GENERIC_READ 또는GENERIC_WRITE 액세스 권한으로 만들어졌어야 합니다. 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.

[in] liDistanceToMove

파일 포인터를 이동할 바이트 수입니다. 양수 값은 파일에서 포인터를 앞으로 이동하고 음수 값은 파일 포인터를 뒤로 이동합니다.

[out, optional] lpNewFilePointer

새 파일 포인터를 받을 변수에 대한 포인터입니다. 이 매개 변수가 NULL이면 새 파일 포인터가 반환되지 않습니다.

[in] dwMoveMethod

파일 포인터 이동의 시작점입니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.

값	의미
FILE_BEGIN 0	시작점이 0이거나 파일의 시작점입니다. 이 플래그를 지정하면 liDistanceToMove 매개 변수가 서명되지 않은 값으로 해석됩니다.
FILE_CURRENT 1	시작점은 파일 포인터의 현재 값입니다.
FILE_END 2	시작점은 현재 파일 끝 위치입니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

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

설명

이 함수에서 반환된 파일 포인터는 겹치는 읽기 및 쓰기 작업에 사용되지 않습니다. 겹치는 작업에 대한 오프셋을 지정하려면 OVERLAPPED 구조체의 Offset 및 OffsetHigh 멤버를 사용합니다.

SetFilePointerEx 함수는 파이프 또는 통신 디바이스와 같이 수신하지 않는 디바이스에 대한 핸들과 함께 사용할 수 없습니다. hFile의 파일 형식을 확인하려면 GetFileType 함수를 사용합니다.

다중 스레드 애플리케이션에서 파일 포인터를 설정할 때는 주의해야 합니다. 공유 리소스에 대한 액세스를 동기화해야 합니다. 예를 들어 스레드가 파일 핸들을 공유하고, 파일 포인터를 업데이트하고, 파일에서 읽는 애플리케이션은 중요한 섹션 개체 또는 뮤텍스 개체를 사용하여 이 시퀀스를 보호해야 합니다. 이러한 개체에 대한 자세한 내용은 중요한 섹션 개체 및 뮤텍스 개체를 참조하세요.

FILE_FLAG_NO_BUFFERING 플래그 집합을 사용하여 hFile 핸들을 연 경우 애플리케이션은 파일 포인터를 섹터 맞춤 위치로만 이동할 수 있습니다. 섹터 정렬 위치는 볼륨 섹터 크기의 정수 배수인 위치입니다. 애플리케이션은 GetDiskFreeSpace 함수를 호출하여 볼륨의 섹터 크기를 가져올 수 있습니다. 애플리케이션이 섹터 정렬되지 않은 위치와 FILE_FLAG_NO_BUFFERING 열린 핸들을 생성하는 이동 거리 값으로 SetFilePointerEx를 호출하면 함수가 실패하고 GetLastError가 ERROR_INVALID_PARAMETER 반환합니다. 자세한 내용은 파일 버퍼링을 참조하세요.

파일 포인터를 파일 끝 너머의 위치로 설정하는 것은 오류가 아닙니다. SetEndOfFile, WriteFile 또는 WriteFileEx 함수를 호출할 때까지 파일 크기가 증가하지 않습니다. 쓰기 작업을 수행하면 파일의 크기가 파일 포인터 위치와 기록된 버퍼의 크기가 증가하므로 중간 바이트가 0으로 초기화됩니다.

SetFilePointerEx를 사용하여 파일 길이를 확인할 수 있습니다. 이렇게 하려면 dwMoveMethod에 FILE_END 사용하고 위치 0을 찾습니다. 반환되는 파일 오프셋은 파일의 길이입니다. 그러나 프로그램이 해당 위치로 돌아갈 수 있도록 현재 파일 포인터를 저장하지 못하는 등의 의도하지 않은 부작용이 있을 수 있습니다. 대신 GetFileSizeEx 함수를 사용하는 것이 더 간단하고 안전합니다.

SetFilePointerEx를 사용하여 현재 파일 포인터 위치를 쿼리할 수도 있습니다. 이렇게 하려면 FILE_CURRENT 이동 메서드와 0의 거리를 지정합니다.

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)	Yes

요구 사항


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