The SetFilePointer function moves the file pointer of an open file.
DWORD SetFilePointer(
HANDLE hFile, |
// handle of file |
LONG lDistanceToMove, |
// number of bytes to move file pointer |
PLONG lpDistanceToMoveHigh, |
// address of high-order word of distance to move |
DWORD dwMoveMethod |
// how to move |
); |
Value |
Meaning |
FILE_BEGIN |
The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, DistanceToMove is interpreted as an unsigned location for the new file pointer. |
FILE_CURRENT |
The current value of the file pointer is the starting point. |
FILE_END |
The current end-of-file position is the starting point. |
If the SetFilePointer function succeeds, the return value is the low-order doubleword of the new file pointer, and if lpDistanceToMoveHigh is not NULL, the function puts the high-order doubleword of the new file pointer into the LONG pointed to by that parameter.
If the function fails and lpDistanceToMoveHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.
If the function fails, and lpDistanceToMoveHigh is non-NULL, the return value is 0xFFFFFFFF and GetLastError will return a value other than NO_ERROR.
You cannot use the SetFilePointer function with a handle to a nonseeking device, such as a pipe or a communications device. To determine the file type for hFile, use the GetFileType function.
You should be careful when setting the file pointer in a multithreaded application. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object. For more information about these objects, see Mutex Objects and Critical Section Objects.
If the hFile file handle was opened with the FILE_FLAG_NO_BUFFERING flag set, an application can move the file pointer only to sector-aligned positions. A sector-aligned position is a position that is a whole number multiple of the volume’s sector size. An application can obtain a volume’s sector size by calling the GetDiskFreeSpace function. If an application calls SetFilePointer with distance-to-move values that result in a position that is not sector-aligned and a handle that was opened with FILE_FLAG_NO_BUFFERING, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.
Note that if the return value is 0xFFFFFFFF and if lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following sample code illustrates this point:
// // Case One: calling the function with // lpDistanceToMoveHigh == NULL // try to move hFile's file pointer some distance dwPointer = SetFilePointer (hFile, lDistance, NULL, FILE_BEGIN) ; // if we failed ... if (dwPointer == 0xFFFFFFFF) { // obtain the error code dwError = GetLastError() ; // deal with that failure . . . } // end of error handler // // Case Two: calling the function with // lpDistanceToMoveHigh != NULL // try to move hFile's file pointer some huge distance dwPointerLow = SetFilePointer (hFile, lDistanceLow, & lDistanceHigh, FILE_BEGIN) ; // if we failed ... if (dwPointerLow == 0xFFFFFFFF && (dwError = GetLastError()) != NO_ERROR ){ // deal with that failure . . . } // end of error handler
GetDiskFreeSpace, GetFileType, ReadFile, ReadFileEx, WriteFile, WriteFileEx
file: /Techref/os/win/api/win32/func/src/f78_20.htm, 7KB, , updated: 2000/4/7 12:19, local time: 2024/8/25 04:51,
18.224.67.29:LOG IN
|
©2024 These pages are served without commercial sponsorship. (No popup ads, etc...).Bandwidth abuse increases hosting cost forcing sponsorship or shutdown. This server aggressively defends against automated copying for any reason including offline viewing, duplication, etc... Please respect this requirement and DO NOT RIP THIS SITE. Questions? <A HREF="http://piclist.com/tecHREF/os/win/api/win32/func/src/f78_20.htm"> SetFilePointer</A> |
Did you find what you needed? |
![]() o List host: MIT, Site host massmind.org, Top posters @none found - Page Editors: James Newton, David Cary, and YOU! * Roman Black of Black Robotics donates from sales of Linistep stepper controller kits. * Ashley Roll of Digital Nemesis donates from sales of RCL-1 RS232 to TTL converters. * Monthly Subscribers: Gregg Rew. on-going support is MOST appreciated! * Contributors: Richard Seriani, Sr. |
Welcome to piclist.com! |
.