setFilePointerEx 函数 (fileapi.h)

  • 项目

移动指定文件的文件指针。

语法

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
 起始点为零或文件的开头。 如果指定了此标志，则 liDistanceToMove 参数将解释为无符号值。
FILE_CURRENT
1
 起点是文件指针的当前值。
FILE_END
2
 起点是当前文件结束位置。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。

注解

此函数返回的文件指针不用于重叠读取和写入操作。 若要指定重叠操作的偏移量，请使用 OVERLAPPED 结构的 Offset 和 OffsetHigh 成员。

不能将 SetFilePointerEx 函数与非视设备（如管道或通信设备）的句柄一起使用。 若要确定 hFile 的文件类型，请使用 GetFileType 函数。

在多线程应用程序中设置文件指针时要小心。 必须同步对共享资源的访问。 例如，其线程共享文件句柄、更新文件指针并从文件读取的应用程序必须使用关键节对象或互斥对象来保护此序列。 有关这些对象的详细信息，请参阅 Critical Section 对象 和 互斥对象。

如果 hFile 句柄打开时设置了 FILE_FLAG_NO_BUFFERING 标志，则应用程序只能将文件指针移动到扇区对齐的位置。 扇区一致位置是卷扇区大小的整数倍的仓位。 应用程序可以通过调用 GetDiskFreeSpace 函数来获取卷的扇区大小。 如果应用程序使用移动距离值调用 SetFilePointerEx ，导致位置不与扇区对齐，并且句柄是使用 FILE_FLAG_NO_BUFFERING 打开的，则函数将失败， GetLastError 将返回 ERROR_INVALID_PARAMETER。 有关其他信息，请参阅 文件缓冲。

请注意，将文件指针设置为文件末尾以外的位置不是错误。 在调用 SetEndOfFile、WriteFile 或 WriteFileEx 函数之前，文件大小不会增加。 写入操作会将文件的大小增加到文件指针位置，以及写入的缓冲区的大小，这会导致干预字节被初始化为零。

可以使用 SetFilePointerEx 来确定文件的长度。 为此，请将 FILE_END 用于 dwMoveMethod 并查找位置零。 返回的文件偏移量是文件的长度。 但是，这种做法可能会产生意外的副作用，例如无法保存当前文件指针，以便程序可以返回到该位置。 改用 GetFileSizeEx 函数更简单、更安全。

还可以使用 SetFilePointerEx 查询当前文件指针位置。 为此，请指定 移动方法FILE_CURRENT ，距离为零。

在 Windows 8 和 Windows Server 2012 中，此函数由以下技术支持。

技术 支持
服务器消息块 (SMB) 3.0 协议 是
SMB 3.0 透明故障转移 (TFO) 是
具有横向扩展文件共享的 SMB 3.0 (SO) 是
群集共享卷文件系统 (CSV) 是
弹性文件系统 (ReFS) 是

要求

   
最低受支持的客户端 Windows XP [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2003 [桌面应用 | UWP 应用]
目标平台 Windows
标头 fileapi.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

文件管理函数

GetDiskFreeSpaceEx

GetFileSizeEx

GetFileType

SetEndOfFile

WriteFile

WriteFileEx