Управляющий код FSCTL_SET_ZERO_DATA заполняет указанную область файла нулями. Если файл разреженный или сжатый, NTFS может освободить дисковое пространство внутри файла. Код устанавливает область нулевых байтов, не расширяя размер файла.
Чтобы выполнить эту операцию, вызовите функцию DeviceIoControl со следующими параметрами.
Синтаксис
BOOL DeviceIoControl( (HANDLE) hDevice, // дескриптор файла FSCTL_SET_ZERO_DATA, // dwIoControlCode (LPVOID) lpInBuffer, // буфер ввода (DWORD) nInBufferSize, // размер буфера ввода NULL, // lpOutBuffer 0, // nOutBufferSize (LPDWORD) lpBytesReturned, // число возвращаемых данных (LPOVERLAPPED) lpOverlapped // структура OVERLAPPED ); |
Параметры
hDevice
[in] Дескриптор файла или выбранного потока, в который будут записаны нулевые данные. Файл должен быть на томе, который является NTFS версии 5.0 или выше. Чтобы извлечь дескриптор файла, используйте функцию CreateFile. Файл не должен быть разреженным файлом.dwIoControlCode
[in] Управляющий код для операции. Для этой операции используйте FSCTL_SET_ZERO_DATA .lpInBuffer
[in] Указатель на структуру FILE_ZERO_DATA_INFORMATION, определяющую область файла, в которой устанавливаются нули. Член структуры FileOffset - смещение первого байта, в котором устанавливаются нули, а член структуры BeyondFinalZero - смещение первого байта после последнего обнуленного байта.nInBufferSize
[in] Размер буфера ввода данных, в байтах.lpOutBuffer
Не используется этой операцией; устанавливается в ПУСТО (NULL).nOutBufferSize
Не используется этой операцией; устанавливается в нуль.lpBytesReturned
[out] Указатель на переменную, которая получает размер данных, сохраненных в буфере вывода данных, в байтах.Если параметр lpOverlapped - ПУСТО (NULL), lpBytesReturned не может быть ПУСТО (NULL). Даже тогда, когда операция не возвращает никакого вывода данных, а параметр lpOutBuffer - ПУСТО (NULL), функция DeviceIoControl использует lpBytesReturned. После такой операции, значение параметра lpBytesReturned становится бессмысленным.
Если параметр lpOverlapped - не ПУСТО (NULL), то - lpBytesReturned может быть ПУСТО (NULL). Если этот параметр - не ПУСТО (NULL) и операция возвращает данные, lpBytesReturned не имеет смысла до тех пор, пока не завершиться асинхронная операция. Чтобы получить данные о числе возвращаемых данных, вызовите функцию GetOverlappedResult. Если параметр hDevice связан с портом завершения ввода-вывода данных (I/O), Вы можете извлечь число возвращаемых данных при помощи вызова функции GetQueuedCompletionStatus.
lpOverlapped
[in] Указатель на структуру OVERLAPPED.Если параметр hDevice открывался без установки флажка FILE_FLAG_OVERLAPPED, параметр lpOverlapped игнорируется.
Если параметр hDevice открывался с флажком FILE_FLAG_OVERLAPPED, операция выполняется как перекрывающая (асинхронная) операция. В этом случае, параметр lpOverlapped должен указать на допустимую структуру OVERLAPPED, которая содержит дескриптор объекта события. Иначе, функция завершается ошибкой непредсказуемыми способами.
Для асинхронных операций, функция DeviceIoControl возвращает значение немедленно, а объект события подает сигнал, когда операция завершается. В противном случае, функция не возвращает значение до тех пор, пока операция не завершится или не произойдет ошибка.
Возвращаемые значения
Если операция завершается успешно, функция DeviceIoControl возвращает не нулевое значение.
Если операция завершается ошибкой, DeviceIoControl возвращает нуль. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.
Замечания
Как включить асинхронный ввод-вывод в эту операцию, см. раздел Замечаний в описании функции DeviceIoControl.
Если Вы используете функцию WriteFile, чтобы записать нули в разреженный файл, файловая система назначает дисковое пространство для данных, которые Вы запишете. Если Вы используете управляющий код FSCTL_SET_ZERO_DATA, чтобы записать нули в разреженный файл, и обнуленная область является достаточно большой, файловая система не сможет распределить дисковое пространство.
Если Вы используете управляющий код FSCTL_SET_ZERO_DATA, чтобы записать нули в не разреженный файл, нули будут записаны в файл. Система распределит дисковый накопитель для вывода всей обнуленной области. Это эквивалентно использованию функции WriteFile, чтобы записать нули в файл.
| Обратите внимание! на то, что для удаленного (сетевого) файла отметки времени правильно не могут быть обновлены. Чтобы гарантировать непротиворечивые результаты, используйте не буферизованный ввод - вывод. |
Обзор Разреженные файлы, Управляющие коды, используемые в управлении файлами, DeviceIoControl, FILE_ZERO_DATA_INFORMATION, FSCTL_QUERY_ALLOCATED_RANGES, FSCTL_SET_SPARSE
|
Размещение и совместимость FSCTL_SET_ZERO_DATA |
||
| К |
Windows XP |
Да |
| л |
Windows 2000 Professional |
Да |
| и |
Windows NT |
Нет |
| е |
Windows Me |
Нет |
| н |
Windows 98 |
Нет |
| т |
Windows 95 |
Нет |
| С |
Windows Server 2003 |
Да |
| е | Windows 2000 Server | Да |
| р | Windows NT Server | Нет |
| в | ||
| е | ||
| р | ||
|
Используемая библиотека |
- |
|
| Используемая DLL | - | |
| Заголовочный файл | ||
|
- объявлено в |
Winioctl.h |
|
| - включено в |
- |
|
| Unicode |
Нет |
|
| Замечания по платформе |
Не имеется |
|