moveFileExA 函数 (winbase.h)

项目
03/03/2024

使用各种移动选项移动现有的文件或目录，包括其子级。

MoveFileWithProgress 函数等效于 MoveFileEx 函数，但 MoveFileWithProgress 允许您提供接收进度通知的回调函数。

若要以事务处理操作的形式执行此操作，请使用 MoveFileTransacted 函数。

语法

BOOL MoveFileExA(
  [in]           LPCSTR lpExistingFileName,
  [in, optional] LPCSTR lpNewFileName,
  [in]           DWORD  dwFlags
);

参数

[in] lpExistingFileName

本地计算机上文件或目录的当前名称。

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT，则文件不能存在于远程共享上，因为延迟的操作是在网络可用之前执行的。

默认情况下，名称限制为MAX_PATH个字符。若要将此限制扩展到 32,767 个宽字符，请在路径前面添加“\\？\”。有关详细信息，请参阅命名文件、路径和命名空间。

提示

从 Windows 10 版本 1607 开始，可以选择删除MAX_PATH限制，而无需在前面添加“\\？\”。有关详细信息，请参阅命名文件、路径和命名空间的“最大路径长度限制”部分。

[in, optional] lpNewFileName

本地计算机上文件或目录的新名称。

移动文件时，目标可以位于不同的文件系统或卷上。如果目标位于另一个驱动器上，则必须在 dwFlags 中设置MOVEFILE_COPY_ALLOWED标志。

移动目录时，目标必须位于同一驱动器上。

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT 且 lpNewFileName 为 NULL， 则 MoveFileEx 将注册 lpExistingFileName 文件，以在系统重新启动时删除。如果 lpExistingFileName 引用目录，则仅当目录为空时，系统才会在重启时删除该目录。

提示

[in] dwFlags

此参数可使用以下一个或多个值。

值	含义
MOVEFILE_COPY_ALLOWED 2 (0x2)	如果要将文件移动到其他卷，该函数将使用 CopyFile 和 DeleteFile 函数模拟移动。如果文件已成功复制到其他卷，并且无法删除原始文件，则函数会成功使源文件保持不变。此值不能与 MOVEFILE_DELAY_UNTIL_REBOOT 一起使用。
MOVEFILE_CREATE_HARDLINK 16 (0x10)	保留供将来使用。
MOVEFILE_DELAY_UNTIL_REBOOT 4 (0x4)	在重新启动操作系统之前，系统不会移动文件。系统在执行 AUTOCHK 之后、创建任何分页文件之前立即移动文件。因此，此参数使函数能够从以前的启动中删除分页文件。仅当进程位于属于管理员组或 LocalSystem 帐户的用户的上下文中时，才能使用此值。此值不能与 MOVEFILE_COPY_ALLOWED一起使用。
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 (0x20)	如果源文件是链接源，则函数失败，但在移动后无法跟踪该文件。如果目标是使用 FAT 文件系统格式化的卷，则可能会出现这种情况。
MOVEFILE_REPLACE_EXISTING 1 (0x1)	如果存在名为 lpNewFileName 的文件，则函数会将其内容替换为 lpExistingFileName 文件的内容，前提是满足有关访问控制列表 (ACL) 的安全要求。有关详细信息，请参阅本主题的“备注”部分。如果 lpNewFileName 命名现有目录，则报告错误。
MOVEFILE_WRITE_THROUGH 8 (0x8)	在磁盘上实际移动文件之前，函数不会返回。设置此值可确保作为复制和删除操作执行的移动在函数返回之前刷新到磁盘。刷新发生在复制操作结束时。如果设置了 MOVEFILE_DELAY_UNTIL_REBOOT ，则此值无效。

返回值

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

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

注解

如果 dwFlags 参数指定 MOVEFILE_DELAY_UNTIL_REBOOT，则 如果无法访问注册表，则 MoveFileEx 将失败。该函数将重新启动时要重命名的文件的位置存储在以下注册表值中： HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\控制\会话管理器\PendingFileRenameOperations

此注册表值的类型为 REG_MULTI_SZ。每个重命名操作存储以下以 NULL 结尾的字符串之一，具体取决于重命名是否为删除：

szDstFile\0\0
szSrcFile\0szDstFile\0

字符串 szDstFile\0\0 指示文件 szDstFile 将在重新启动时删除。字符串 szSrcFile\0szDstFile\0 指示 szSrcFile 将在重新启动时重命名为 szDstFile 。

注意尽管在技术上不允许 在REG_MULTI_SZ 节点中使用 \0\0，但它是因为它被视为重命名为空名称。

系统使用这些注册表项在重启时按照它们发出的相同顺序完成操作。例如，以下代码片段创建删除 szDstFile 的注册表项，并在重启时将 szSrcFile 重命名为 szDstFile ：

MoveFileEx(szDstFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

由于使用 MOVEFILE_DELAY_UNTIL_REBOOT 标志指定的实际移动和删除操作是在调用应用程序停止运行后发生的，因此返回值无法反映移动或删除文件的成功或失败。相反，它反映了将相应条目放入注册表中的成功与否。

仅当目录为空时，系统才会删除标记为 要删除的MOVEFILE_DELAY_UNTIL_REBOOT 标志的目录。若要确保删除目录，请在尝试删除目录之前从目录中移动或删除所有文件。在启动时，文件可能位于目录中，但必须先删除或移动这些文件，系统才能删除目录。

移动和删除操作在启动时按在调用应用程序中指定的顺序执行。若要在启动时删除包含文件的目录，请先删除文件。

如果文件跨卷移动， MoveFileEx 不会随文件一起移动安全描述符。文件在目标目录中分配默认安全描述符。

MoveFileEx 函数将其操作与链接跟踪服务协调，因此可以在移动链接源时对其进行跟踪。

若要删除或重命名文件，必须具有对文件的删除权限或父目录中的删除子权限。如果设置了除删除和删除子级以外的所有访问权限的目录，并且新文件的 ACL 继承，则应该能够创建文件而不删除该文件。但是，你可以创建一个文件，并获取你在创建文件时返回给你的句柄上请求的所有访问权限。如果在创建文件时请求删除权限，则可以使用该句柄删除或重命名文件，但不能使用任何其他句柄来删除或重命名该文件。有关详细信息，请参阅文件安全和访问权限。

在 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
标头	winbase.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll