please dont rip this site Prev Next

SetFilePointer info  Overview  Group

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

   );

Parameters

hFile
Identifies the file whose file pointer is to be moved. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file.
lDistanceToMove
Specifies the number of bytes to move the file pointer. A positive value moves the pointer forward in the file and a negative value moves it backward.
lpDistanceToMoveHigh
Points to the high-order word of the 64-bit distance to move. If the value of this parameter is NULL, SetFilePointer can operate only on files whose maximum size is 2^32 - 2. If this parameter is specified, the maximum file size is 2^64 - 2. This parameter also receives the high-order word of the new value of the file pointer.
dwMoveMethod
Specifies the starting point for the file pointer move. This parameter can be one of the following values:

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.

Return Values

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.

Remarks

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 

 

See Also

GetDiskFreeSpace, GetFileType, ReadFile, ReadFileEx, WriteFile, WriteFileEx

See also:


file: /Techref/os/win/api/win32/func/src/f78_20.htm, 7KB, , updated: 2000/4/7 12:19, local time: 2022/5/18 02:48,
TOP NEW HELP FIND: 
44.192.25.113:LOG IN

 ©2022 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?
Please DO link to this page! Digg it! / MAKE!

<A HREF="http://www.piclist.com/techref/os/win/api/win32/func/src/f78_20.htm"> SetFilePointer</A>

After you find an appropriate page, you are invited to your to this massmind site! (posts will be visible only to you before review) Just type a nice message (short messages are blocked as spam) in the box and press the Post button. (HTML welcomed, but not the <A tag: Instead, use the link box to link to another page. A tutorial is available Members can login to post directly, become page editors, and be credited for their posts.


Link? Put it here: 
if you want a response, please enter your email address: 
Attn spammers: All posts are reviewed before being made visible to anyone other than the poster.
Did you find what you needed?

  PICList 2022 contributors:
o List host: MIT, Site host massmind.org, Top posters @20220518
* 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 www.piclist.com!

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

  .