SetFilePointer 함수(fileapi.h)
지정된 파일의 파일 포인터를 이동합니다.
이 함수는 파일 포인터를 두 개의 LONG 값에 저장합니다. 단일 LONG 값보다 큰 파일 포인터를 사용하려면 SetFilePointerEx 함수를 사용하는 것이 더 쉽습니다.
구문
DWORD SetFilePointer(
[in] HANDLE hFile,
[in] LONG lDistanceToMove,
[in, out, optional] PLONG lpDistanceToMoveHigh,
[in] DWORD dwMoveMethod
);
매개 변수
[in] hFile
파일에 대한 핸들입니다.
GENERIC_READ 또는 GENERIC_WRITE 액세스 권한으로 파일 핸들 을 만들어야 합니다. 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.
[in] lDistanceToMove
파일 포인터를 이동할 바이트 수를 지정하는 부호 있는 값의 하위 순서 32비트입니다.
lpDistanceToMoveHigh가 NULL이 아닌 경우 lpDistanceToMoveHigh 및 lDistanceToMove는 이동할 거리를 지정하는 단일 64비트 부호 있는 값을 형성합니다.
lpDistanceToMoveHigh가 NULL이면 lDistanceToMove는 32비트 부호 있는 값입니다. lDistanceToMove에 대한 양수 값은 파일에서 파일 포인터를 앞으로 이동하고 음수 값은 파일 포인터를 뒤로 이동합니다.
[in, out, optional] lpDistanceToMoveHigh
이동할 부속 64비트 거리의 상위 32비트 포인터입니다.
높은 순서의 32비트(high order 32비트)가 필요하지 않은 경우 이 포인터를 NULL로 설정해야 합니다.
NULL이 아닌 경우 이 매개 변수는 파일 포인터의 새 값에 대한 높은 순서의 DWORD도 받습니다. 자세한 내용은 이 항목의 설명 섹션을 참조하세요.
[in] dwMoveMethod
파일 포인터 이동의 시작점입니다.
이 매개 변수는 다음 값 중 하나일 수 있습니다.
| 값 | 의미 |
|---|---|
|
시작점은 0이거나 파일의 시작점입니다. |
|
시작점은 파일 포인터의 현재 값입니다. |
|
시작점은 현재 파일 끝 위치입니다. |
반환 값
함수가 성공하고 lpDistanceToMoveHigh 가 NULL이면 반환 값은 새 파일 포인터의 하위 순서 DWORD 입니다. 참고 함수가 INVALID_SET_FILE_POINTER 이외의 값을 반환하는 경우 SetFilePointer 에 대한 호출이 성공했습니다. GetLastError를 호출할 필요가 없습니다.
함수가 성공하고 lpDistanceToMoveHigh 가 NULL이 아닌 경우 반환 값은 새 파일 포인터의 하위 순서 DWORD 이고 lpDistanceToMoveHigh 에는 새 파일 포인터의 상위 DWORD 가 포함됩니다.
함수가 실패하면 반환 값이 INVALID_SET_FILE_POINTER. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
새 파일 포인터가 음수 값이면 함수가 실패하고 파일 포인터가 이동되지 않으며 GetLastError 에서 반환된 코드가 ERROR_NEGATIVE_SEEK.
lpDistanceToMoveHigh가 NULL이고 새 파일 위치가 32비트 값에 맞지 않으면 함수가 실패하고 INVALID_SET_FILE_POINTER 반환합니다.
설명
hFile 매개 변수의 값으로 식별되는 파일 포인터는 겹치는 읽기 및 쓰기 작업에 사용되지 않습니다.
hFile 매개 변수는 검색 디바이스에 저장된 파일을 참조해야 합니다. 예를 들어 디스크 볼륨입니다. SetFilePointer 함수가 오류를 반환하지 않더라도 파이프 또는 통신 디바이스와 같은 검색되지 않는 디바이스에 대한 핸들을 사용하여 SetFilePointer 함수를 호출하는 것은 지원되지 않습니다. 이 경우 SetFilePointer 함수의 동작은 정의되지 않습니다.
겹치는 작업의 오프셋을 지정하려면
- OVERLAPPED 구조체의 Offset 및 OffsetHigh 멤버를 사용합니다.
hFile의 파일 형식을 확인하려면
- GetFileType 함수를 사용합니다.
다중 스레드 애플리케이션에서 파일 포인터를 설정할 때는 주의해야 합니다. 공유 리소스에 대한 액세스를 동기화해야 합니다. 예를 들어 파일 핸들을 공유하고, 파일 포인터를 업데이트하고, 파일에서 읽는 스레드가 있는 애플리케이션은 중요한 섹션 개체 또는 뮤텍스 개체를 사용하여 이 시퀀스를 보호해야 합니다. 자세한 내용은 중요 섹션 개체 및 뮤텍스 개체를 참조하세요.
hFile 핸들이 FILE_FLAG_NO_BUFFERING 플래그 집합으로 열려 있는 경우 애플리케이션은 파일 포인터를 섹터 맞춤 위치로만 이동할 수 있습니다. 섹터 정렬 위치는 볼륨 섹터 크기의 정수 배수인 위치입니다. 애플리케이션은 GetDiskFreeSpace 함수를 호출하여 볼륨 섹터 크기를 가져올 수 있습니다.
애플리케이션이 거리와 함께 SetFilePointer 를 호출하여 섹터 정렬되지 않은 위치와 FILE_FLAG_NO_BUFFERING 열린 핸들을 생성하는 값을 이동하면 함수가 실패하고 GetLastError 가 ERROR_INVALID_PARAMETER 반환합니다.
파일 포인터를 파일 끝의 위치로 설정하는 것은 오류가 아닙니다. SetEndOfFile, WriteFile 또는 WriteFileEx 함수를 호출할 때까지 파일 크기가 증가하지 않습니다. 쓰기 작업을 수행하면 파일의 크기가 파일 포인터 위치와 기록된 버퍼의 크기로 증가하므로 중간 바이트가 0으로 초기화됩니다.
반환 값이 INVALID_SET_FILE_POINTERlpDistanceToMoveHigh 가 NULL이 아닌 경우 애플리케이션은 GetLastError 를 호출하여 함수가 성공했는지 실패했는지 여부를 확인해야 합니다. 다음 코드 예제에서는 해당 시나리오를 보여줍니다.
// Case One: calling the function with lpDistanceToMoveHigh == NULL
// Try to move hFile file pointer some distance
DWORD dwPtr = SetFilePointer( hFile,
lDistance,
NULL,
FILE_BEGIN );
if (dwPtr == INVALID_SET_FILE_POINTER) // Test for failure
{
// Obtain the error code.
DWORD dwError = GetLastError() ;
// Deal with failure
// . . .
} // End of error handler
//
// Case Two: calling the function with lpDistanceToMoveHigh != NULL
// Try to move hFile file pointer a huge distance
DWORD dwPtrLow = SetFilePointer( hFile,
lDistLow,
&lDistHigh,
FILE_BEGIN );
// Test for failure
if ( dwPtrLow == INVALID_SET_FILE_POINTER &&
GetLastError() != NO_ERROR )
{
// Deal with failure
// . . .
} // End of error handler
lpDistanceToMoveHigh 매개 변수는 거대한 파일을 조작하는 데 사용되지만 모든 크기의 파일을 이동할 때 매개 변수 값을 설정해야 합니다. NULL로 설정된 경우 모든 파일 포인터 값이 부호 있는 값이므로 lDistanceToMove의 최대값은 2^31-2 또는 2GB 미만입니다. 따라서 파일이 해당 크기로 증가할 가능성이 적으면 파일을 거대한 파일로 처리하고 64비트 파일 포인터로 작업하는 것이 가장 좋습니다. NTFS 파일 시스템에서 파일 압축 및 스파스 파일을 사용하면 기본 볼륨이 크지 않더라도 큰 파일을 가질 수 있습니다.
lpDistanceToMoveHigh가 NULL이 아닌 경우 lpDistanceToMoveHigh 및 lDistanceToMove는 단일 64비트 부호 있는 값을 형성합니다. lDistanceToMove 매개 변수는 값의 하위 32비트로 처리되고 lpDistanceToMoveHigh는 상위 32비트로 처리됩니다. 즉, lpDistanceToMoveHigh는 lDistanceToMove의 기호 확장입니다.
파일 포인터를 0에서 2기가바이트로 이동하려면 lpDistanceToMoveHigh 를 NULL 또는 lDistanceToMove의 기호 확장으로 설정해야 합니다. 포인터를 2기가바이트 이상 이동하려면 lpDistanceToMoveHigh 및 lDistanceToMove 를 단일 64비트 수량으로 사용합니다. 예를 들어 2기가바이트에서 4기가바이트 범위로 이동하려면 ldistanceToMoveHigh 의 콘텐츠를 0으로 설정하거나 lDistanceToMove의 음수 기호 확장의 경우 –1로 설정합니다.
64비트 파일 포인터를 사용하려면 LONG을 선언하고, 64비트 파일 포인터의 상위 절반으로 처리하고, lpDistanceToMoveHigh에서 해당 주소를 전달할 수 있습니다. 즉, 두 개의 서로 다른 변수를 논리 단위로 처리해야 하므로 오류가 발생할 수 있습니다. LARGE_INTEGER 구조를 사용하여 64비트 값을 만들고 공용 구조체의 적절한 요소를 사용하여 두 개의 32비트 값을 전달하는 것이 가장 좋습니다.
또한 함수를 사용하여 SetFilePointer에 대한 인터페이스를 숨기는 것이 가장 좋습니다. 다음 코드 예제에서는 해당 시나리오를 보여줍니다.
__int64 myFileSeek (HANDLE hf, __int64 distance, DWORD MoveMethod)
{
LARGE_INTEGER li;
li.QuadPart = distance;
li.LowPart = SetFilePointer (hf,
li.LowPart,
&li.HighPart,
MoveMethod);
if (li.LowPart == INVALID_SET_FILE_POINTER && GetLastError()
!= NO_ERROR)
{
li.QuadPart = -1;
}
return li.QuadPart;
}
SetFilePointer를 사용하여 파일 길이를 확인할 수 있습니다. 이렇게 하려면 dwMoveMethod에 FILE_END 사용하고 위치 0을 찾습니다. 반환되는 파일 오프셋은 파일의 길이입니다. 그러나 프로그램이 해당 위치로 돌아갈 수 있도록 현재 파일 포인터를 저장하지 못하는 등의 의도하지 않은 부작용이 있을 수 있습니다. 대신 GetFileSize를 사용하는 것이 가장 좋습니다.
SetFilePointer 함수를 사용하여 현재 파일 포인터 위치를 쿼리할 수도 있습니다. 이렇게 하려면 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) | 예 |
예제
파일을 추가하는 코드 예제는 한 파일을 다른 파일에 추가를 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | fileapi.h(Windows.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |
참고 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기