rename() - Unix、Linux系统调用

名称

rename - 更改文件名称或位置

概要

#include <stdio.h>

int rename(const char *oldpath, const char *newpath);

描述

rename() 重命名文件，如果需要，可在目录之间移动文件。

任何其他指向该文件的硬链接（如使用link(2)创建的）都不会受到影响。

如果newpath已存在，它将被原子地替换（受一些条件限制；请参见下面的错误），因此不会出现另一个尝试访问newpath的进程发现它不存在的情况。

如果newpath存在但操作由于某种原因失败，rename() 保证保留newpath的实例。

但是，在覆盖时，可能会有一个窗口，其中oldpath和newpath都指向正在重命名的文件。

如果oldpath指向符号链接，则重命名链接；如果newpath指向符号链接，则覆盖链接。

返回值

成功时，返回零。发生错误时，返回 -1，并相应地设置errno。

错误

标签	描述
EACCES	对包含oldpath或newpath的目录的写权限被拒绝，或者对oldpath或newpath路径前缀中的某个目录的搜索权限被拒绝，或者oldpath是一个目录并且不允许写权限（需要更新..条目）。（另见path_resolution(2)。）
EBUSY	重命名失败，因为oldpath或newpath是某个进程正在使用的目录（可能作为当前工作目录或根目录，或者因为它已打开以进行读取）或系统正在使用的目录（例如作为挂载点），而系统认为这是一个错误。（请注意，不需要在这种情况下返回EBUSY——无论如何进行重命名都没有问题——但是如果系统无法以其他方式处理这种情况，则允许返回EBUSY。）
EFAULT	oldpath或newpath指向您可访问的地址空间之外。
EINVAL	新的路径名包含旧路径名的路径前缀，或者更一般地说，尝试将目录设置为自身的子目录。
EISDIR	newpath是现有目录，但oldpath不是目录。
ELOOP	在解析oldpath或newpath时遇到太多符号链接。
EMLINK	oldpath已经拥有指向它的最大链接数，或者它是一个目录，并且包含newpath的目录拥有最大链接数。
ENAMETOOLONG
	oldpath或newpath过长。
ENOENT	oldpath或newpath中的目录组件不存在或是不存在的符号链接。
ENOMEM	可用的内核内存不足。
ENOSPC	包含该文件的设备没有空间用于新的目录条目。
ENOTDIR
	在oldpath或newpath中用作目录的组件实际上不是目录。或者，oldpath是一个目录，newpath存在但不是目录。
ENOTEMPTY 或 EEXIST
	newpath是一个非空目录，即包含“.”和“..”以外的条目。
EPERM 或 EACCES
	包含oldpath的目录设置了粘滞位（S_ISVTX），并且进程的有效用户 ID 既不是要删除的文件的用户 ID，也不是包含它的目录的用户 ID，并且进程没有特权（Linux：没有CAP_FOWNER功能）；或者newpath是一个现有文件，并且包含它的目录设置了粘滞位，并且进程的有效用户 ID 既不是要替换的文件的用户 ID，也不是包含它的目录的用户 ID，并且进程没有特权（Linux：没有CAP_FOWNER功能）；或者包含pathname的文件系统不支持请求类型的重命名。
EROFS	文件位于只读文件系统上。
EXDEV	oldpath和newpath不在同一个已挂载的文件系统上。（Linux允许将文件系统挂载在多个点上，但是rename(2)不跨不同的挂载点工作，即使在两个挂载点上挂载了相同的文件系统。）

符合标准

4.3BSD、C89、POSIX.1-2001。

缺陷

在NFS文件系统上，您不能假设如果操作失败则文件未被重命名。如果服务器执行重命名操作然后崩溃，则当服务器启动时将处理的重新传输的RPC会导致失败。应用程序应该处理这个问题。有关类似问题，请参见link(2)。

参见

打印页面