Функция SetFileValidData (fileapi.h)

Статья
08/23/2023

Задает допустимую длину данных указанного файла. Эта функция полезна в очень ограниченных сценариях. Дополнительные сведения см. в разделе «Примечания».

Осторожностью Использование этой функции без надлежащих соображений безопасности может поставить под угрозу конфиденциальность и безопасность данных. Дополнительные сведения см. в разделе «Примечания».

Синтаксис

BOOL SetFileValidData(
  [in] HANDLE   hFile,
  [in] LONGLONG ValidDataLength
);

Параметры

[in] hFile

Дескриптор файла. Файл должен быть открыт с правом доступа GENERIC_WRITE и включенной привилегией SE_MANAGE_VOLUME_NAME . Дополнительные сведения см. в разделе Безопасность файлов и права доступа.

Примечание Файл не может быть сетевым, сжатым, разреженным или транзакциям.

[in] ValidDataLength

Новая допустимая длина данных.

Этот параметр должен быть положительным значением, превышающим текущую допустимую длину данных, но меньше текущего размера файла.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция завершается сбоем, возвращаемое значение равно 0. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Размер файла: размер данных в файле до байта.
Размер выделения: размер пространства, выделенного для файла на диске, который всегда кратен размеру кластера.
Допустимая длина данных: длина данных в файле, который фактически записан в байт. Это значение всегда меньше или равно размеру файла.

Как правило, функция SetFileValidData используется приложениями системного уровня для собственных частных данных. Не все файловые системы используют допустимую длину данных. Некоторые файловые системы могут отслеживать несколько допустимых диапазонов данных. Как правило, большинству приложений никогда не нужно вызывать эту функцию.

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

При первоначальном открытии файла у вызывающего объекта должна быть включена привилегия SE_MANAGE_VOLUME_NAME . Приложения должны вызывать SetFileValidData только для файлов, которые ограничивают доступ к сущностям, имеющим SE_MANAGE_VOLUME_NAME доступ. Приложение должно гарантировать, что неписанные диапазоны файла никогда не будут доступны, иначе могут возникнуть проблемы с безопасностью, как показано ниже.

Если в файле используется SetFileValidData , возможное повышение производительности достигается путем не заполнения выделенных кластеров для файла нулями. Таким образом, при чтении из файла будут возвращены все выделенные кластеры, потенциально содержимое от других пользователей. На данном этапе это не обязательно является проблемой безопасности, так как вызывающий объект должен иметь SE_MANAGE_VOLUME_NAME привилегии для успешного выполнения SetFileValidData , а все данные на диске могут быть прочитаны такими пользователями. Однако этот вызывающий объект может непреднамеренно предоставить эти данные другим пользователям, которые не могут получить привилегию SE_MANAGE_VOLUME_PRIVILEGE , если имеет следующее:

Если файл не был открыт в режиме общего доступа, который запрещает другим читателям, непривилегированный пользователь может открыть его и прочитать предоставленные данные.
Если система перестает отвечать до того, как вызывающий объект завершит запись ValidDataLength , предоставленного в вызове, то при перезагрузке такой непривилегированный пользователь может открыть файл и прочитать предоставленное содержимое.

Если вызывающий объект SetFileValidData открыл файл с достаточно строгим контролем доступа, предыдущие условия не будут применяться. Однако для частично записанных файлов, расширенных с помощью SetFileValidData (т. е. запись не была завершена до ValidDataLength , предоставленного в вызове), существует еще одна потенциальная уязвимость конфиденциальности или безопасности. Администратор может скопировать файл в целевой объект, который не контролируется с помощью ограниченных разрешений ACL, что непреднамеренно подвергает данные расширенной области несанкционированным считывания.

Именно по этим причинам setFileValidData не рекомендуется использовать для общего назначения, помимо соображений производительности, как описано ниже.

Дополнительные сведения о привилегиях безопасности и доступа см. в разделах Запуск со специальными привилегиями и Безопасность файлов и Права доступа.

Функцию SetFileValidData можно использовать для создания больших файлов в очень конкретных обстоятельствах, чтобы производительность последующих файловых операций ввода-вывода была выше, чем в других методах. В частности, если расширенная часть файла является большой и будет записана случайным образом, например в приложении типа базы данных, то время, необходимое для расширения и записи в файл, будет быстрее, чем при использовании SetEndOfFile и записи случайным образом. В большинстве других ситуаций при использовании SetFileValidData обычно нет повышения производительности, а иногда может возникнуть снижение производительности.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
SMB 3.0 Transparent Failover (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Требования


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

См. также

Функции управления файлами

SetEndOfFile