CreateHardLinkA 関数 (winbase.h)

[アーティクル]
11/20/2024

既存のファイルと新しいファイルの間にハードリンクを確立します。この関数は NTFS ファイルシステムでのみサポートされ、ディレクトリではなくファイルに対してのみサポートされます。

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

構文

BOOL CreateHardLinkA(
  [in] LPCSTR                lpFileName,
  [in] LPCSTR                lpExistingFileName,
       LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

パラメーター

[in] lpFileName

新しいファイルの名前。

このパラメーターにはパスを含めることができますが、ディレクトリの名前を指定することはできません。

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

先端

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

[in] lpExistingFileName

既存のファイルの名前。

このパラメーターには、ディレクトリの名前を指定できないパスを含めることができます。

先端

lpSecurityAttributes

引っ込み思案;は NULLする必要があります。

戻り値

関数が成功した場合、戻り値は 0 以外です。

関数が失敗した場合、戻り値はゼロ (0) になります。拡張エラー情報を取得するには、GetLastError呼び出します。

この関数で作成できるハードリンクの最大数は、ファイルあたり 1023 です。ファイルに対して 1023 を超えるリンクが作成されると、エラーが発生します。

この関数の ANSI バージョンの lpFileName または lpExistingFileName パラメーターにMAX_PATH文字より長い名前を渡す場合、またはパスに "\\?\" を指定せずにこの関数の Unicode バージョンに渡すと、関数はERROR_PATH_NOT_FOUNDを返します。

備考

CreateFile または CreateHardLink を使用して作成されたファイルのディレクトリエントリは、関連付けられているファイルへのハードリンクです。 CreateHardLink 関数を使用して作成される追加のハードリンクを使用すると、ファイルに対して複数のディレクトリエントリを作成できます。つまり、同じファイルへの複数のハードリンク (同じディレクトリ内の異なる名前でも、異なるディレクトリ内の同じ名前でも異なる名前でもかまいません)。ただし、ファイルへのハードリンクはすべて同じボリューム上にある必要があります。

ハードリンクはファイルのディレクトリエントリのみであるため、そのファイルに対する多くの変更は、そのファイルを参照するハードリンクを介してアクセスするアプリケーションにすぐに表示されます。ただし、ディレクトリエントリのサイズと属性の情報は、変更が行われたリンクに対してのみ更新されます。

セキュリティ記述子は、ハードリンクが指すファイルに属しています。リンク自体はディレクトリエントリのみで、セキュリティ記述子はありません。したがって、ハードリンクのセキュリティ記述子を変更すると、基になるファイルのセキュリティ記述子が変更され、ファイルを指すすべてのハードリンクで新しく指定されたアクセスが許可されます。ハードリンクごとにファイルに異なるセキュリティ記述子を指定することはできません。

この関数は、lpSecurityAttributes パラメーターにセキュリティ記述子情報が渡された場合でも、リンク先のファイルのセキュリティ記述子を変更しません。

DeleteFile を使用して、ハードリンクを削除します。作成された順序に関係なく、任意の順序で削除できます。

CreateFile で指定されているフラグ、属性、アクセス、および共有は、ファイルごとに動作。つまり、共有を許可しないファイルを開くと、別のアプリケーションがファイルへの新しいハードリンクを作成してファイルを共有することはできません。

NTFS ファイルシステムでハードリンクを作成すると、ディレクトリエントリ内のファイル属性情報が更新されるのは、ファイルが開かれている場合、または GetFileInformationByHandle が特定のファイルのハンドルで呼び出されたときだけです。

シンボリックリンクの動作 : パスがシンボリックリンクを指している場合、関数はシンボリックリンクへのハードリンクを作成します。

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

テクノロジー	サポート
サーバーメッセージブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 透過的フェールオーバー (TFO)	いいえ
SMB 3.0 とスケールアウトファイル共有 (SO)	いいえ
クラスター共有ボリュームファイルシステム (CsvFS)	はい
回復性のあるファイルシステム (ReFS)	いいえ

SMB 3.0 では、継続的な可用性機能を備えた共有へのハードリンクの作成はサポートされていないことに注意してください。

例

次のコードスニペットは、CreateHardLink 呼び出して、ファイルのセキュリティ記述子を変更しないようにする方法を示しています。 pszExistingFileName パラメーターには、元のファイル名またはファイルへの既存のリンクを指定できます。このコードが実行された後、pszNewLinkName はファイルを参照します。

  BOOL fCreatedLink = CreateHardLink( pszNewLinkName, 
                                      pszExistingFileName, 
                                      NULL ); // reserved, must be NULL

  if ( fCreatedLink == FALSE )
   {
    ;// handle error condition
   }

手記

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

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリのみ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	winbase.h (Windows.h を含む)
ライブラリ	Kernel32.lib
DLL	Kernel32.dll

次の方法で共有

CreateHardLinkA 関数 (winbase.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース