CreateHardLinkA 関数 (winbase.h)

[アーティクル]
03/03/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 パラメーター、またはパスに "\\?\" を事前に指定せずに Unicode バージョンのこの関数に、MAX_PATH文字より長い名前を渡すと、関数はERROR_PATH_NOT_FOUNDを返します。

注釈

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

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

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

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

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

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

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

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

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

テクノロジ	サポートされています
サーバーメッセージブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 Transparent Failover (TFO)	いいえ
スケールアウトファイル共有 (SO) を使う SMB 3.0	いいえ
クラスターの共有ボリュームファイルシステム (CsvFS)	はい
Resilient File System (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 ヘッダーは、CreateHardLink をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

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

CreateHardLinkA 関数 (winbase.h)

構文

パラメーター

戻り値

注釈

例

要件

関連項目

フィードバック

フィードバック

その他のリソース