rename 或 renameat 子例程

在线编辑

用途

请重命名目录或文件。

库

标准 C 库 (libc.a)

语法

#include <stdio.h>
int rename ( FromPath,  ToPath)
const char *FromPath, *ToPath;

int renameat (DirFileDescriptor1, FromPath, DirFileDescriptor2,
ToPath)
int DirFileDescriptor1, DirFileDescriptor2;
const char *FromPath, *ToPath;

描述

重命名 和 雷纳梅特 子例程将文件系统中的目录或文件重命名。 如果 DirFileDescriptor1 和 DirFileDescriptor2 都是 AT_FDCWD 或 FromPath 和 ToPath 参数都是绝对路径名，那么 renameat 子例程等同于重命名子例程。

要使用任一子例程，调用进程必须在 FromPath 和 ToPath 参数的父目录中具有写和搜索许可权。 如果 renameat 子例程中的 DirFileDescriptor1 或 DirFileDescriptor2 参数所指向的目录是在没有 O_SEARCH 打开标志的情况下打开的，那么子例程将检查以确定是否允许使用该目录的当前许可权对该目录进行目录搜索。 但是，如果任一目录是使用 搜索 打开标志打开的，那么子例程不会对该目录执行检查。 如果 FromPath 参数中定义的路径是一个目录，那么调用进程还必须具有对 FromPath 目录的写和搜索许可权。 如果 FromPath 和 ToPath 参数都引用同一现有文件，那么这两个子例程都将成功返回并且不会执行其他操作。

FromPath 和 ToPath 参数的组件必须具有相同类型 (即，两个目录或两个非目录) ，并且必须位于同一文件系统上。 如果 ToPath 文件已存在，那么将首先除去该文件。 除去它将保证在整个操作中存在名为 ToPath 的链接。 此链接引用在操作开始之前由 ToPath 或 FromPath 参数指定的文件。

如果 FromPath 参数的最终组件是符号链接，那么将重命名符号链接 (而不是它指向的文件或目录)。 如果 ToPath 是符号链接，那么会破坏该链接。

如果 FromPath 参数的父目录具有 粘性位属性 (在 <sys/mode.h> 文件中描述) ，那么调用进程必须具有等于 FromPath 参数的所有者标识或 FromPath 参数的父目录的所有者标识的有效用户标识。

不是该文件或目录的所有者的用户必须具有 root 用户权限才能使用 重命名 子例程。

如果 FromPath 和 ToPath 参数名称目录，那么必须满足以下条件:

  • FromPath 参数指定的目录不是 ToPath的祖代。 例如， FromPath 路径名不得包含对 ToPath 参数指定的目录进行命名的路径前缀。
  • FromPath 参数中指定的目录必须格式正确。 格式正确的目录同时包含这两个内容。 （点）和 .. (点点) 条目。 那就是那个 FromPath 目录中的 (点) 条目引用的目录与 FromPath 参数中的目录相同。 那 ...  FromPath 目录中的 (点点) 条目是指包含 FromPath条目的目录。
  • ToPath 参数指定的目录 (如果存在) 必须格式正确 (如先前所定义)。

参数

项 描述
DirFileDescriptor1 指定打开的目录的文件描述符。
DirFileDescriptor2 指定打开的目录的文件描述符。
FromPath 标识要重命名的文件或目录。 如果指定了 DirFileDescriptor1 ，并且 FromPath 是相对路径名，那么将 FromPath 视为相对于 DirFileDescriptor1指定的目录。
ToPath 标识要重命名的文件或目录的新路径名。 如果指定了 DirFileDescriptor2 并且 ToPath 是相对路径名，那么将 ToPath 视为相对于 DirFileDescriptor2指定的目录。 如果 ToPath 是现有文件或空目录，那么会将其替换为 FromPath。 如果 ToPath 指定不为空的目录，那么 rename 子例程将退出并返回错误。

返回值

在成功完成后， 重命名 和 雷纳梅特 子例程将返回值 0。 否则，将返回 -1 的值，并设置 errno 全局变量来指示错误。

错误代码

重命名 或 雷纳梅特 子例程不成功，并且如果下列其中一个或多个条件成立，那么文件或目录名称保持不变:

项 描述
EACCES 创建请求的链接需要以拒绝进程写许可权的目录方式进行写入。
EBUSY 系统当前正在使用由 FromPath 或 ToPath 参数指定的目录，或者由 FromPath 或 ToPath 指定的文件是指定的 STREAM。
EDQUOT 无法扩展将包含 ToPath 参数指定的路径的目录，因为包含该目录的文件系统上用户或组的磁盘块配额已耗尽。
EEXIST ToPath 参数指定不为空的现有目录。
EINVAL FromPath 或 ToPath 参数中指定的路径不是格式正确的目录 (FromPath 是 ToPath的祖代) ，或者已尝试重命名。 (点) 或 .. （点点）。
EISDIR ToPath 参数指定目录， FromPath 参数指定非目录。
EMLINK FromPath 参数指定的目录大于 ToPath 参数的父目录的最大链接计数。
ENOENT 路径的组件不存在，由 FromPath 参数指定的文件不存在，或者指定了符号链接，但它所引用的文件不存在。
ENOSPC 无法扩展将包含 ToPath 参数中指定的路径的目录，因为文件系统空间不足。
ENOTDIR FromPath 参数指定目录， ToPath 参数指定非目录。
ENOTEMPTY ToPath 参数指定不为空的现有目录。
EROFS 所请求的操作需要写入只读文件系统上的目录。
ETXTBSY ToPath 参数指定当前正在使用的共享文本文件。
扩展 DEV 由 ToPath 参数指定的链接和由 FromPath 参数指定的文件位于不同的文件系统上。

雷纳梅特 子例程不成功，并且如果下列其中一项或多项成立，那么文件或目录名称保持不变:

项 描述
EACCES 未使用 搜索 标志打开 DirFileDescriptor1 或 DirFileDescriptor2 参数所指向的目录，并且该目录的许可权不允许目录搜索。
EBADF 路径参数未指定绝对路径，相应的 DirFileDescriptor 参数既不是 AT_FDCWD ，也不是有效的文件描述符。
ENOTDIR 路径参数不指定绝对路径，相应的 DirFileDescriptor 参数既不是 AT_FDCWD ，也不是与目录相关的文件描述符。

如果系统上安装了网络文件系统 (NFS) ，那么如果满足以下条件，那么 rename 和 renameat 子例程可能会失败:

项 描述
ETIMEDOUT 连接已超时。

重命名 和 雷纳梅特 子例程可能由于其他原因而不成功。