_utime、、_utime32_utime64、_wutime、、_wutime32、_wutime64
設定檔案修改時間。
語法
int _utime(
const char *filename,
struct _utimbuf *times
);
int _utime32(
const char *filename,
struct __utimbuf32 *times
);
int _utime64(
const char *filename,
struct __utimbuf64 *times
);
int _wutime(
const wchar_t *filename,
struct _utimbuf *times
);
int _wutime32(
const wchar_t *filename,
struct __utimbuf32 *times
);
int _wutime64(
const wchar_t *filename,
struct __utimbuf64 *times
);
參數
filename
包含路徑或檔名之字串的指標。
times
預存時間值的指標。
傳回值
如果檔案修改時間變更，則所有這些函式都會傳回 0。 -1 的傳回值表示錯誤。 如果傳遞了無效的參數，則會叫用無效的參數處理程式，如參數驗證中所述。 如果允許繼續執行，這些函式會傳回 -1，並 errno 設定為下列其中一個值：
errno 值 |
Condition |
|---|---|
EACCES |
路徑指定目錄或唯讀檔案 |
EINVAL |
無效的 times 引數 |
EMFILE |
開啟太多檔案 (必須開啟檔案，才能變更其修改時間) |
ENOENT |
找不到路徑或檔名 |
如需傳回碼的詳細資訊，請參閱errno、 _doserrno_sys_errlist和 _sys_nerr。
如果變更日期晚於 1970 年 1 月 1 日午夜，且早於所使用函式的結束日期，則可以變更檔案的日期。 _utime 和 _wutime 使用 64 位元時間值，因此結束日期是 3000 年 12 月 31 日 23:59:59 (UTC)。 如果 _USE_32BIT_TIME_T 定義成強制執行舊行為，則結束日期是 2038 年 1 月 18 日 23:59:59 (UTC)。 不論是否定義 _USE_32BIT_TIME_T，_utime32 或 _wutime32 都會使用 32 位元時間類型，而且一律會有最早的結束日期。 _utime64 或 _wutime64 一律會使用 64 位元時間類型，因此這些函式一律會支援較新的結束日期。
備註
函 _utime 式會設定 所 filename指定檔案的修改時間。 處理序必須具有檔案的寫入權，才能變更時間。 在 Windows 作業系統中，您可以變更 _utimbuf 結構中的存取時間和修改時間。 如果 times 是 NULL 指標，則修改時間設定為目前當地時間。 否則，times 必須指向定義於 SYS\UTIME.H 且類型為 _utimbuf 的結構。
_utimbuf 結構會儲存 _utime 所使用的檔案存取和修改時間，以變更檔案修改日期。 此結構具有下列都屬於類型 time_t 的欄位：
| 欄位 | 描述 |
|---|---|
actime |
檔案存取的時間 |
modtime |
檔案修改的時間 |
特定版本的 _utimbuf 結構 (__utimbuf32 和 __utimbuf64) 是使用 32 位元和 64 位元版本的時間類型所定義。 這些結構用於此函式的 32 位和 64 位特定版本。 除非定義 _USE_32BIT_TIME_T，否則 _utimbuf 本身預設會使用 64 位元時間類型。
_utime 等同於 _futime，不同之處在於 _utime 的 filename 引數是檔案的檔名或路徑，而不是開啟檔案的檔案描述元。
_wutime 是寬字元版本的 _utime； filename 的 _wutime 引數是寬字元字串。 除此之外，這些函式的行為相同。
根據預設，此函式的全域狀態會限定於應用程式。 若要變更此行為，請參閱 CRT 中的全域狀態。
一般文字常式對應
| TCHAR.H 常式 | _UNICODE 和 _MBCS 未定義 |
_MBCS 已定義 |
_UNICODE 已定義 |
|---|---|---|---|
_tutime |
_utime |
_utime |
_wutime |
_tutime32 |
_utime32 |
_utime32 |
_wutime32 |
_tutime64 |
_utime64 |
_utime64 |
_wutime64 |
需求
| 常式 | 必要標頭 | 選擇性標頭 |
|---|---|---|
_utime、 、 _utime32_utime64 |
<sys/utime.h> | <errno.h> |
_utime64 |
<sys/utime.h> | <errno.h> |
_wutime |
<utime.h> 或 <wchar.h> | <errno.h> |
如需相容性詳細資訊，請參閱相容性。
範例
此程式會使用 _utime，以將檔案修改時間設為目前時間。
// crt_utime.c
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/utime.h>
#include <time.h>
int main( void )
{
struct tm tma = {0}, tmm = {0};
struct _utimbuf ut;
// Fill out the accessed time structure
tma.tm_hour = 12;
tma.tm_isdst = 0;
tma.tm_mday = 15;
tma.tm_min = 0;
tma.tm_mon = 0;
tma.tm_sec = 0;
tma.tm_year = 103;
// Fill out the modified time structure
tmm.tm_hour = 12;
tmm.tm_isdst = 0;
tmm.tm_mday = 15;
tmm.tm_min = 0;
tmm.tm_mon = 0;
tmm.tm_sec = 0;
tmm.tm_year = 102;
// Convert tm to time_t
ut.actime = mktime(&tma);
ut.modtime = mktime(&tmm);
// Show file time before and after
system( "dir crt_utime.c" );
if( _utime( "crt_utime.c", &ut ) == -1 )
perror( "_utime failed\n" );
else
printf( "File time modified\n" );
system( "dir crt_utime.c" );
}
範例輸出
Volume in drive C has no label.
Volume Serial Number is 9CAC-DE74
Directory of C:\test
01/09/2003 05:38 PM 935 crt_utime.c
1 File(s) 935 bytes
0 Dir(s) 20,742,955,008 bytes free
File time modified
Volume in drive C has no label.
Volume Serial Number is 9CAC-DE74
Directory of C:\test
01/15/2002 12:00 PM 935 crt_utime.c
1 File(s) 935 bytes
0 Dir(s) 20,742,955,008 bytes free
另請參閱
時間管理
asctime, _wasctime
ctime、、_ctime32_ctime64、_wctime、、_wctime32、_wctime64
_fstat、、_fstat32_fstat64、_fstati64、、_fstat32i64、_fstat64i32
_ftime、 、 _ftime32_ftime64
_futime、 、 _futime32_futime64
gmtime、 、 _gmtime32_gmtime64
localtime、 、 _localtime32_localtime64
_stat、_wstat 函式
time、 、 _time32_time64