Функция IoCreateFile (wdm.h)

Статья
08/08/2023

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

Синтаксис

NTSTATUS IoCreateFile(
  [out]          PHANDLE            FileHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in, optional] PLARGE_INTEGER     AllocationSize,
  [in]           ULONG              FileAttributes,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options
);

Параметры

[out] FileHandle

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

[in] DesiredAccess

Битовая маска флагов, указывающая тип доступа к файлу или каталогу, которые требуются вызывающей системе. Дополнительные сведения об этом параметре и списке значений флагов см. в разделе Параметр DesiredAccessioCreateFileEx .

[in] ObjectAttributes

Указатель на непрозрачную структуру OBJECT_ATTRIBUTES , которая уже инициализирована с помощью InitializeObjectAttributes. Дополнительные сведения и описание каждого элемента структуры см. в разделе Параметр ObjectAttributesобъекта IoCreateFileEx .

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK , которая получает окончательное состояние завершения и сведения о запрошенной операции. См. параметр IoStatusBlockобъекта IoCreateFileEx.

[in, optional] AllocationSize

При необходимости задает начальный размер выделения файла в байтах. Ненулевое значение не оказывает никакого влияния, если только файл не создается, не перезаписывается или не заменяет его.

[in] FileAttributes

Явно указанные атрибуты применяются только при создании, замене или перезаписи файла. По умолчанию это значение FILE_ATTRIBUTE_NORMAL, которое может быть переопределено сочетанием ORed из одного или нескольких флагов FILE_ATTRIBUTE_XXX , определенных в Wdm.h. Список флагов, которые можно использовать с IoCreateFile, см. в разделе CreateFile.

[in] ShareAccess

Указывает тип общего доступа к файлу, который требуется вызывающей организации, как ноль или единица, или сочетание флагов. Дополнительные сведения и список флагов см. в разделе Параметр ShareAccessIoCreateFileEx .

[in] Disposition

Задает значение, определяющее выполняемое действие в зависимости от того, существует ли файл. Список возможных значений см. в разделе Параметр ЛиквидацияIoCreateFileEx .

[in] CreateOptions

Указывает параметры, применяемые при создании или открытии файла. Этот параметр является совместимым сочетанием флагов, перечисленных и описанных в параметре CreateOptionsобъекта IoCreateFileEx.

[in, optional] EaBuffer

Для драйверов устройств и промежуточных драйверов этот параметр должен быть указателем NULL .

[in] EaLength

Для драйверов устройств и промежуточных драйверов этот параметр должен быть равен нулю.

[in] CreateFileType

Драйверы должны задать для этого параметра значение CreateFileTypeNone.

[in, optional] InternalParameters

Драйверы должны задать для этого параметра значение NULL.

[in] Options

Указывает параметры, используемые во время создания запроса на создание. Список возможных параметров см. в разделе ПараметрыIoCreateFileEx .

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

IoCreateFile возвращает STATUS_SUCCESS или соответствующее состояние ошибки. Значение NTSTATUS. Список возможных кодов возврата см. в разделе Возвращаемое значениеioCreateFileEx .

Подпрограмма IoCreateFileEx аналогична процедуре IoCreateFile , но предоставляет больше функциональных возможностей, чем процедура IoCreateFile , включая доступ к дополнительным параметрам создания (ECP), объектам устройств и сведениям о транзакциях.

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

Существует два альтернативных способа указать имя файла, который будет создан или открыт с помощью IoCreateFile:

В качестве полного имени пути, указанного в элементе ObjectName входных атрибутов ObjectAttributes.
Значение pathname относительно файла каталога, представленного дескриптором в элементе RootDirectory входного объекта ObjectAttributes.

Некоторые флаги DesiredAccess и их сочетания имеют следующие эффекты:

Чтобы вызывающий объект синхронизировать завершение ввода-вывода, ожидая возвращаемого объекта FileHandle, необходимо установить флаг SYNCHRONIZE. В противном случае вызывающий объект, который является устройством или промежуточным драйвером, должен синхронизировать завершение ввода-вывода с помощью объекта события.
Если заданы только флаги FILE_APPEND_DATA и SYNCHRONIZE, вызывающий объект может записывать данные только в конец файла, а любые сведения о смещении записей в файл игнорируются. Однако файл будет автоматически расширен по мере необходимости для операции записи этого типа.
Установка флага FILE_WRITE_DATA для файла также позволяет выполнять операции записи за пределами конца файла. Файл также автоматически расширяется для этого типа записи.
Если заданы только флаги FILE_EXECUTE и SYNCHRONIZE, вызывающий объект не может напрямую считывать или записывать какие-либо данные в файле с помощью возвращенного fileHandle, то есть все операции с файлом выполняются через системный пейджер в ответ на инструкции и доступ к данным. Драйверы устройств и промежуточных драйверов не должны устанавливать флаг FILE_EXECUTE в DesiredAccess.

Параметр ShareAccess определяет, могут ли отдельные потоки получать доступ к одному файлу, возможно, одновременно. При условии, что оба средства открытия файлов имеют права доступа к файлу указанным способом, файл можно успешно открыть и предоставить к ним общий доступ. Если исходный вызывающий объект IoCreateFile не указывает FILE_SHARE_READ, FILE_SHARE_WRITE или FILE_SHARE_DELETE, другие открытые операции с файлом выполняться невозможно, то есть исходному вызывающему объекту предоставляется монопольный доступ к файлу.

Чтобы общий файл был успешно открыт, запрошенный объект DesiredAccess к файлу должен быть совместим со спецификациями DesiredAccess и ShareAccess всех предыдущих открытий, которые еще не были выпущены с помощью ZwClose. То есть значение DesiredAccess , указанное в IoCreateFile для данного файла, не должно конфликтовать с доступом, запрещенным другими средствами открытия файла.

Значение ликвидации FILE_SUPERSEDE требует, чтобы вызывающий объект был доступ DELETE к существующему объекту файла. Если это так, успешный вызов IoCreateFile с FILE_SUPERSEDE в существующем файле эффективно удаляет этот файл, а затем повторно создает его. Это означает, что, если файл уже был открыт другим потоком, он открыл файл, указав параметр ShareAccessс флагом FILE_SHARE_DELETE. Обратите внимание, что этот тип ликвидации соответствует стилю POSIX для перезаписи файлов.

Значения ликвидации FILE_OVERWRITE_IF и FILE_SUPERSEDE похожи. Если ioCreateFile вызывается с существующим файлом и любое из этих значений Ликвидации , файл будет заменен.

Перезапись файла семантически эквивалентна операции замены, за исключением следующего:

Вызывающий объект должен иметь доступ на запись к файлу, а не доступ к удалению. Это означает, что, если файл уже был открыт другим потоком, он открыл файл с флагом FILE_SHARE_WRITE, установленным во входном shareAccess.
Указанные атрибуты файла логически являются ORed с атрибутами, уже имеющимися в файле. Это означает, что если файл уже открыт другим потоком, последующий вызывающий объект IoCreateFile не может отключить существующие флаги FileAttributes , но может включить дополнительные флаги для того же файла.

Значение FILE_DIRECTORY_FILE CreateOptions указывает, что создаваемый или открытый файл является файлом каталога. При создании файла каталога файловая система создает соответствующую структуру на диске, которая представляет пустой каталог для структуры на диске конкретной файловой системы. Если этот параметр был указан, а открываемый файл не является файлом каталога или если вызывающий объект указал несогласованное значение CreateOptions или Disposition , вызов IoCreateFile завершится ошибкой.

Флаг FILE_NO_INTERMEDIATE_BUFFERING CreateOptions запрещает файловой системе выполнять промежуточную буферизацию от имени вызывающего объекта. Если указать это значение, параметры вызывающего объекта накладывают определенные ограничения на подпрограммы ZwXxxFile , в том числе следующие:

Любой необязательный Параметр ByteOffset , передаваемый в ZwReadFile или ZwWriteFile, должен быть неотъемлемой частью размера сектора.
Длина, передаваемая в ZwReadFile или ZwWriteFile, должна быть целой частью размера сектора. Обратите внимание, что указание операции чтения в буфер, длина которого точно равна размеру сектора, может привести к тому, что в этот буфер будет передано меньшее количество байтов, если во время передачи был достигнут конец файла.
Буферы должны быть выровнены в соответствии с требованиями к выравниванию базового устройства. Эти сведения можно получить, вызвав IoCreateFile , чтобы получить дескриптор для объекта файла, представляющего физическое устройство, а затем вызвав ZwQueryInformationFile с этим дескриптором. Список системных значений FILE_XXX_ALIGNMENT см. в разделе DEVICE_OBJECT.
Вызовы ZwSetInformationFile с параметром FileInformationClass , равным FilePositionInformation, должны указывать смещение, являющееся целой частью размера сектора.

В FILE_SYNCHRONOUS_IO_ALERT CreateOptions и FILE_SYNCHRONOUS_IO_NONALERT, которые являются взаимоисключающими, как предполагают их имена, указывают, что все операции ввода-вывода с файлом должны быть синхронными, если они происходят через объект файла, на который ссылается возвращаемый FileHandle. Все операции ввода-вывода в таком файле сериализуются во всех потоках с помощью возвращенного дескриптора. При использовании любого из этих свойств CreateOptions необходимо установить флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал файловый объект в качестве объекта синхронизации. При использовании любого из этих наборов CreateOptions диспетчер операций ввода-вывода поддерживает "контекст позиции файла" для объекта файла, внутреннее смещение текущей позиции файла. Это смещение можно использовать в вызовах ZwReadFile и ZwWriteFile. Его положение также можно запрашивать или задавать с помощью ZwQueryInformationFile и ZwSetInformationFile.

Если флаг createOptions FILE_OPEN_REPARSE_POINT не указан и IoCreateFile пытается открыть файл с точкой повторного обработки, для файла выполняется обычная обработка точки повторного обработки. С другой стороны, если указан флаг FILE_OPEN_REPARSE_POINT, обычная обработка повторного обработки не выполняется и IoCreateFile пытается открыть файл точки повторного обработки напрямую. В любом случае, если операция открытия была успешной, IoCreateFile возвращает STATUS_SUCCESS; В противном случае подпрограмма возвращает код ошибки NTSTATUS. IoCreateFile никогда не возвращает STATUS_REPARSE.

Флаг CreateOptions FILE_OPEN_REQUIRING_OPLOCK исключает время между открытием файла и запросом блокировки, что потенциально может позволить третьей стороне открыть файл и получить нарушение общего доступа. Приложение может использовать флаг FILE_OPEN_REQUIRING_OPLOCK в IoCreateFile , а затем запрашивать любую блокировку. Это гарантирует, что владелец операции будет уведомлен о любом последующем открытом запросе, который приведет к нарушению общего доступа.

В Windows 7, если в файле существуют другие дескрипторы, когда приложение использует флаг FILE_OPEN_REQUIRING_OPLOCK, операция создания завершится сбоем с STATUS_OPLOCK_NOT_GRANTED. Это ограничение больше не существует, начиная с Windows 8.

Если эта операция создания приведет к прерыванию блокировки, которая уже существует в файле, установка флага FILE_OPEN_REQUIRING_OPLOCK приведет к сбою операции создания с STATUS_CANNOT_BREAK_OPLOCK. Существующая блокировка не будет нарушена этой операцией создания.

Приложение, использующее флаг FILE_OPEN_REQUIRING_OPLOCK, должно запросить блокировку после успешного вызова, иначе все последующие попытки открыть файл будут заблокированы без обычной обработки блокировки. Аналогичным образом, если этот вызов завершается успешно, но последующий запрос oplock завершается сбоем, приложение, использующее этот флаг, должно закрыть свой дескриптор после обнаружения сбоя запроса на блокировку.

Флаг FILE_OPEN_REQUIRING_OPLOCK доступен в Windows 7, Windows Server 2008 R2 и более поздних версиях Windows. Файловые системы Майкрософт, реализующие этот флаг в Windows 7, — NTFS, FAT и exFAT.

Флаг CreateOptions , FILE_RESERVE_OPFILTER, позволяет приложению запрашивать oplock уровня 1, пакет или фильтрацию, чтобы предотвратить нарушения общего доступа в других приложениях. Однако FILE_RESERVE_OPFILTER удобно использовать только для блокировки фильтров. Чтобы использовать его, необходимо выполнить следующие действия:

Отправьте запрос на создание с параметром CreateOptions FILE_RESERVE_OPFILTER, DesiredAccess точно FILE_READ_ATTRIBUTES и ShareAccess точно FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Если дескрипторы уже открыты, запрос на создание завершается ошибкой с STATUS_OPLOCK_NOT_GRANTED, а следующая запрошенная блокировка также завершается ошибкой.
- При открытии с большим доступом или меньшим общим доступом также произойдет сбой STATUS_OPLOCK_NOT_GRANTED.
Если запрос на создание выполнен успешно, запросите блокировку операции.
Откройте другой дескриптор файла для выполнения операций ввода-вывода.

Шаг 3 делает это практичным только для фильтров oplock. Дескриптор, открытый на шаге 3, может иметь desiredAccess , который содержит не более FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL и по-прежнему не прерывает блокировку фильтра. Однако любой объект DesiredAccess больше FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | Функция SYNCHRONIZE разорвёт блокировку на уровне 1 или пакетную блокировку и сделает флаг FILE_RESERVE_OPFILTER бесполезным для этих типов oplock.

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

Если для запросов на создание, исходящих в пользовательском режиме, драйвер задает IO_NO_PARAMETER_CHECKING и IO_FORCE_ACCESS_CHECK в параметре Optionsобъекта IoCreateFile , он также должен задать OBJ_FORCE_ACCESS_CHECK в параметре ObjectAttributes . Сведения об этом флаге см. в разделе АтрибутыOBJECT_ATTRIBUTES.

NTFS — единственная файловая система Майкрософт, реализующая FILE_RESERVE_OPFILTER.

Подпрограммы драйвера, которые выполняются в контексте процесса, отличном от контекста системного процесса, должны задавать атрибут OBJ_KERNEL_HANDLE для параметра ObjectAttributesобъекта IoCreateFile. Это ограничивает использование дескриптора, возвращаемого IoCreateFile , процессами, выполняемыми только в режиме ядра. В противном случае дескриптор может получить доступ к процессу, в контексте которого выполняется драйвер. Драйверы могут вызывать InitializeObjectAttributes , чтобы задать атрибут OBJ_KERNEL_HANDLE следующим образом.

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)