CopyFileA 関数 (winbase.h)

  • [アーティクル]

既存のファイルを新しいファイルにコピーします。

CopyFileEx 関数には、2 つの追加機能があります。 CopyFileEx は、コピー操作の一部が完了するたびに指定されたコールバック関数を呼び出すことができます。コピー操作中に CopyFileEx を取り消すことができます。

この操作をトランザクション操作として実行するには、 CopyFileTransacted 関数を使用します。

構文

BOOL CopyFileA(
  [in] LPCSTR lpExistingFileName,
  [in] LPCSTR lpNewFileName,
  [in] BOOL   bFailIfExists
);

パラメーター

[in] lpExistingFileName

既存のファイルの名前。

既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前に置かずに、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 ファイル、パス、および名前空間の名前付け 」の「最大パス長の制限」セクションを参照してください。

lpExistingFileName が存在しない場合、CopyFile は失敗し、GetLastError はERROR_FILE_NOT_FOUNDを返します。

[in] lpNewFileName

新しいファイルの名前。

既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前に置かずに、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 ファイル、パス、および名前空間の名前付け 」の「最大パス長の制限」セクションを参照してください。

[in] bFailIfExists

このパラメーターが TRUE で、 lpNewFileName で指定された新しいファイルが既に存在する場合、関数は失敗します。 このパラメーターが FALSE で、新しいファイルが既に存在する場合、関数は既存のファイルを上書きして成功します。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

既存のファイルのセキュリティ リソース プロパティ (ATTRIBUTE_SECURITY_INFORMATION) が新しいファイルにコピーされます。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: 既存のファイルのセキュリティ リソース プロパティは、Windows 8してWindows Server 2012するまで新しいファイルにコピーされません。

既存のファイルのファイル属性が新しいファイルにコピーされます。 たとえば、既存のファイルに FILE_ATTRIBUTE_READONLY ファイル属性がある場合、 CopyFile の呼び出しによって作成されたコピーには 、FILE_ATTRIBUTE_READONLY ファイル属性も含まれます。 詳細については、「 ファイル属性の取得と変更」を参照してください。

変換先ファイルが既に存在し、 FILE_ATTRIBUTE_HIDDEN または FILE_ATTRIBUTE_READONLY 属性が設定されている場合、この関数は ERROR_ACCESS_DENIED で失敗します。

CopyFile を使用して暗号化されたファイルをコピーすると、コピー元ファイルの暗号化に使用されるキーを使用して、コピー先ファイルの暗号化が試みられます。 これができない場合、この関数は既定のキーを使用して宛先ファイルの暗号化を試みます。 どちらの方法も実行できない場合、 CopyFile は ERROR_ENCRYPTION_FAILED エラー コードで失敗します。

シンボリック リンクの動作 : ソース ファイルがシンボリック リンクの場合、コピーされた実際のファイルがシンボリック リンクのターゲットになります。

宛先ファイルが既に存在し、シンボリック・リンクである場合、シンボリック・リンクのターゲットはソース・ファイルによって上書きされます。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル はい
SMB 3.0 Transparent Failover (TFO) はい
スケールアウト ファイル共有 (SO) を使う SMB 3.0 はい
クラスターの共有ボリューム ファイル システム (CsvFS) はい
Resilient File System (ReFS) はい
 

例

例については、「 ファイル属性の取得と変更」を参照してください。

注意

winbase.h ヘッダーは、CopyFile をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

CopyFileEx

CopyFileTransacted

CreateFile

ファイル属性定数

File Management 関数

MoveFile

シンボリック リンク