utime() - Unix 和 Linux 系統呼叫

名稱

utime、utimes - 更改 inode 的訪問和/或修改時間

語法

#include <sys/types.h> 
#include <utime.h> 

int utime(const char *filename, const struct utimbuf *buf); 

#include <sys/time.h> 

int utimes(const char *filename, const struct timeval times[2]);

描述

utime() 將由 filename 指定的 inode 的訪問和修改時間分別更改為 buf 的 actime 和 modtime 欄位。

如果 buf 為 NULL，則將檔案的時間戳設定為當前時間。

在以下情況下允許更改時間戳：程序具有相應的許可權（Linux：具有 CAP_FOWNER 功能），或者有效使用者 ID 等於檔案的所有者 ID，或者 buf 必須為 NULL 並且程序對檔案具有寫許可權。

utimbuf 結構如下所示：

struct utimbuf {
    time_t actime;       /* access time */
    time_t modtime;      /* modification time */
};

函式 utime() 允許以 1 秒的解析度指定時間戳。函式 utimes() 類似，但允許以 1 微秒的解析度指定時間戳。此處 times[0] 指訪問時間，times[1] 指修改時間。

timeval 結構如下所示：

struct timeval {
    long tv_sec;        /* seconds */
    long tv_usec;       /* microseconds */
};

返回值

成功時，返回 0。錯誤時，返回 -1，並且 errno 被適當地設定。

錯誤

標籤	描述
EACCES	path 字首中的某個目錄的搜尋許可權被拒絕（另請參見 path_resolution(2)），或者 buf 為 NULL 並且程序沒有許可權更改時間戳（請參見上文）。
ENOENT	filename 不存在。
EPERM	buf 不為 NULL 並且程序沒有許可權更改時間戳。
EROFS	path 位於只讀檔案系統上。

備註

Linux 不允許更改不可變檔案的時間戳，也不允許將時間戳設定為追加檔案以外的其他時間。

在 libc4 和 libc5 中，utimes() 只是 utime() 的包裝器，因此不允許亞秒級解析度。

POSIX.1-2001 將 utimes() 標記為傳統功能，這很奇怪，因為它提供了比 utime() 更多的功能。

缺陷

Linux 沒有仔細區分 EACCES 和 EPERM 錯誤返回。另一方面，POSIX.1-2001 在其 utimes() 錯誤描述中存在缺陷。

符合標準

utime()：SVr4、POSIX.1-2001。

utimes()：4.3BSD

參見

列印頁面