_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 値	条件
EACCES	パスにディレクトリまたは読み取り専用ファイルが指定されている
EINVAL	無効な times 引数
EMFILE	開いているファイルが多すぎる (変更時刻を変更するにはファイルを開く必要があります)
ENOENT	パスまたはファイル名が見つからない

リターン コードの詳細については、「errno、_doserrno、_sys_errlist、および _sys_nerr」を参照してください。

変更日が 1970 年 1 月 1 日午前 0 時以降で、使用する関数の終了日より前の場合、ファイルの日付を変更できます。 _utime と _wutime は 64 ビットの時刻値を使用するため、終了日は UTC の 3000 年 12 月 31 日 23 時 59 分 59 秒になります。 以前の動作を強制するよう _USE_32BIT_TIME_T が定義されている場合、終了日は UTC の 2038 年 1 月 18 日 23 時 59 分 59 秒になります。 _utime32 または _wutime32 は、_USE_32BIT_TIME_T の定義内容に関係なく 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 ビット固有のバージョンで使用されます。 _utimbuf 自体は、_USE_32BIT_TIME_T が定義されていない場合、既定で 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>

互換性の詳細については、「 Compatibility」を参照してください。

例

このプログラムは _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