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)。

參見

列印頁面