SetFilePointer

SetFilePointer

오픈되고 있는 파일의 파일 포인터를 이동합니다.

DWORD SetFilePointer(
    HANDLE hFile,          // 파일 핸들
    LONG   lDistance,      // 하위 오프셋
    PLONG  pDistanceHigh,  // 상위 오프셋의 변수
    DWORD  dwMoveMethod    // 이동 개시점
);

KERNEL32.DLL

인수

hFile

파일의 핸들을 지정합니다.이 핸들은, GENERIC_READ 액세스 또는 GENERIC_WRITE 액세스를 가지고 있지 않으면 안됩니다.

lDistance

파일 포인터를 이동시키는 아르바이트수를 나타내는 부호 수치의 하위32비트를 지정합니다.

pDistanceHigh 파라미터에 0 (NULL) (을)를 지정했을 경우는, 새로운 파일 포인터의 위치의 오프셋을 나타내는 부호 첨부32비트치를 지정합니다.

pDistanceHigh 파라미터에 유효한 변수의 주소를 지정했을 경우는, 새로운 파일 포인터의 위치의 오프셋의 하위32비트치를 지정합니다. lDistance 파라미터로 지정된 값과 pDistanceHigh 파라미터로 지정되는 변수에 격납되고 있는 값으로 나타내지는 부호 첨부64비트치가 새로운 파일 포인터의 위치의 오프셋이 됩니다.

정의 값을 지정하면 순서 방향으로, 부의 값을 지정하면 역방향으로 이동합니다.

pDistanceHigh

오프셋의 상위32비트치를 격납한 변수의 주소 또는 0 (NULL) (을)를 지정합니다.

변수의 주소를 지정했을 경우는, 함수가 성공하면, 이 변수에 파일 포인터의 새로운 위치의 상위32비트치가 격납됩니다.

이 파라미터에 변수의 주소를 지정하면 오프셋치로서 최대 (2⁶³ - 2) 까지를 지정할 수 있습니다만,0 (NULL) (을)를 지정하면 최대 (2³¹ - 2) 까지 밖에 지정할 수 없습니다.

Windows 95/98/Me： 이 파라미터에 유효한 주소를 지정하는 경우는, 그 변수에는, 0 ,0xFFFFFFFF (INVALID_SET_FILE_POINTER) , 또는 lDistance 파라미터의 부호 확장중 한쪽이 격납되어 있지 않으면 안됩니다.

dwMoveMethod

파일 포인터 이동의 개시점을 지정합니다.다음의 값의 어느쪽이든을 지정합니다.

치	의미
0 (FILE_BEGIN)	파일의 선두를 이동 개시점으로 합니다.
1 (FILE_CURRENT)	현재의 파일 포인터의 위치를 이동 개시점으로 합니다.
2 (FILE_END)	파일의 종단을 이동 개시점으로 합니다.

반환값

함수가 성공하면, 새로운 파일 포인터의 위치를 나타내는 부호 없음 수치의 하위32비트가 돌아갑니다.또, pDistanceHigh 파라미터에 유효한 변수의 주소를 지정했을 경우에는, 그 변수에 상위32비트치가 격납됩니다.

함수가 실패하면, 0xFFFFFFFF (INVALID_SET_FILE_POINTER) 하지만 돌아갑니다.확장 에러 정보를 취득하려면 , GetLastError 함수를 사용합니다.

pDistanceHigh 파라미터에 유효한 변수를 지정했을 경우, 함수가 성공해도 반환값 0xFFFFFFFF (INVALID_SET_FILE_POINTER) 하지만 돌려주어져 버리는 일이 있습니다.이것은 함수 소환 후가 새로운 파일 포인터의 하위32비트치가 0xFFFFFFFF (이)가 되는 경우에 일어납니다.이 경우, 함수가 성공하고 있으면 GetLastError 함수는 0 (NO_ERROR) (을)를 돌려줍니다.

새로운 파일 포인터의 위치가 음수가 되는 경우는, 함수는 실패하고, GetLastError 함수는 131 (ERROR_NEGATIVE_SEEK) (을)를 돌려줍니다.

해설

hFile 파라미터로 지정되는 파일의 파일 포인터는, 비동기의 독해 및 써 조작에서는 사용되지 않습니다.비동기의 조작으로 오프셋을 지정하려면 , OVERLAPPED 구조체의 Offset 멤버 및 OffsetHigh 멤버를 사용합니다.

파일 포인터를 파일 종단 위치의 뒤로 설정할 수 있습니다.파일 사이즈는 SetEndOfFile 함수, WriteFile 함수, WriteFileEx 함수가 불려 갈 때까지는 증가되지 않습니다.기입 조작에서는, 파일 포인터의 위치와 실제로 써진 버퍼의 사이즈의 화가 파일 사이즈가 됩니다.이 때, 사이에 있는 영역은 미초기화 상태가 됩니다.

SetFilePointer 함수는, 파일 포인터의 이동 오프셋에 0 (을)를, 이동 개시점에 FILE_CURRENT (을)를 지정하는 것으로, 현재의 파일 포인터의 위치를 취득할 수 있습니다.

대응 정보

Windows 95 이후 / Windows NT 3.1 이후