Функция 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). Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Максимальное количество жестких ссылок, которые можно создать с помощью этой функции, составляет 1023 на файл. Если для файла создаются более 1023 ссылок, результаты ошибки.

Если вы передаете имя дольше MAX_PATH символов в lpFileName или параметр lpExistingFileName версии ANSI этой функции или в версию юникода этой функции без предварительной привязки "\\?\\", функция возвращает 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 определяет CreateHardLink как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll