Функция CreateHardLinkW (winbase.h)

Статья
06/02/2023

Устанавливает жесткую связь между существующим и новым файлом. Эта функция поддерживается только в файловой системе NTFS и только для файлов, а не каталогов.

Чтобы выполнить эту операцию как транзакцию, используйте функцию CreateHardLinkTransacted .

Синтаксис

BOOL CreateHardLinkW(
  [in] LPCWSTR               lpFileName,
  [in] LPCWSTR               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 Transparent Failover (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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll