CreateHardLinkA 関数 (winbase.h)
既存のファイルと新規のファイルの間にハード リンクを確立します。 この関数は 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
既存のファイルの名前。
このパラメーターには、ディレクトリの名前を指定できないパスを含めることができます。
既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。
ヒント
Windows 10 バージョン 1607 以降では、"\\?\" を前に置かずに、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 ファイル、パス、および名前空間の名前付け 」の「最大パス長の制限」セクションを参照してください。
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 |