_utime、_utime32、_utime64、_wutime、_wutime32、_wutime64

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

ファイルの変更時刻を設定します。

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 は次のいずれかの値に設定されます。

EACCES
パスの指定がディレクトリまたは読み取り専用ファイルになっています。
EINVAL
無効な times 引数です。
EMFILE
開いているファイルが多すぎます。変更時刻を変更するには、対象ファイルを開く必要があります。
ENOENT
パスまたはファイル名が見つかりません。

戻り値の詳細については、「_doserrno、errno、_sys_errlist、および _sys_nerr」を参照してください。

ファイルの日付は、変更する日付が 1970 年 1 月 1 日午前 0 時以降で、使用する関数の終了日以前であれば変更できます。Visual C++ 2005 では、_utime と _wutime は 64 ビットの時刻値を使用するので、終了日は世界協定時刻 (UTC) 3000 年 12 月 31 日 23 時 59 分 59 秒になります。以前のバージョンの動作を実行するように _USE_32BIT_TIME_T が定義されている場合、終了日は UTC の 2038 年 1 月 19 日 3 時 14 分 7 秒です。_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 型の以下の 2 つのフィールドがあります。

actime
ファイルのアクセス時刻。
modtime
ファイルの変更時刻。

Visual C++ 2005 では、_utimbuf 構造体の特定のバージョン (_utimebuf32 と __utimbuf64) が 32 ビットと 64 ビットのバージョンの時刻型を使用して定義されます。これらは、32 ビットおよび 64 ビットに固有なバージョンの関数で使用されます。_utimbuf は、_USE_32BIT_TIME_T が定義されていなければ、既定で 64 ビットの時刻型を使用します。

_utime は、_utime の filename 引数が開いているファイルのファイル記述子ではなく、ファイルの名前またはパスであることを除いて、_futime と同じです。

_wutime 関数は、_utime 関数のワイド文字バージョンです。_wutime 関数の引数 filename は、ワイド文字列です。それ以外では、これらの関数の動作は同じです。

汎用テキストルーチンのマップ

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>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

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