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

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

Синтаксис

NTSYSAPI NTSTATUS ZwCreateFile(
  [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              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Параметры

[out] FileHandle

Указатель на переменную HANDLE, которая получает дескриптор файла.

[in] DesiredAccess

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

Не указывайте FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA или FILE_EXECUTE при создании или открытии каталога.

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

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

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

Дополнительные сведения о правах доступа см. в ACCESS_MASK.

[in] ObjectAttributes

Указатель на структуру OBJECT_ATTRIBUTES , указывающую имя объекта и другие атрибуты. Используйте InitializeObjectAttributes для инициализации этой структуры. Если вызывающий объект не запущен в контексте системного потока, он должен задать атрибут OBJ_KERNEL_HANDLE при вызове InitializeObjectAttributes.

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK , которая получает окончательное состояние завершения и другие сведения о запрошенной операции. В частности, член Information получает одно из следующих значений:

• FILE_CREATED

• FILE_OPENED

• FILE_OVERWRITTEN

• FILE_SUPERSEDED

• FILE_EXISTS

• FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Указатель на LARGE_INTEGER, содержащий начальный размер выделения в байтах для созданного или перезаписываемого файла. Если значение AllocationSize равно NULL, размер выделения не указан. Если файл не создан или перезаписан, функция AllocationSize игнорируется.

[in] FileAttributes

Указывает один или несколько флагов FILE_ATTRIBUTE_XXXX , представляющих атрибуты файла, которые необходимо задать при создании или перезаписи файла. Вызывающий объект обычно задает FILE_ATTRIBUTE_NORMAL, который задает атрибуты по умолчанию. Список допустимых флагов FILE_ATTRIBUTE_XXXX см. в подпрограмме CreateFile . Если файл не создан или перезаписан, FileAttributes игнорируется.

[in] ShareAccess

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

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

[in] CreateDisposition

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

[in] CreateOptions

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

[in, optional] EaBuffer

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

[in] EaLength

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

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

ZwCreateFile возвращает STATUS_SUCCESS при успешном выполнении или соответствующем коде ошибки NTSTATUS при сбое. В последнем случае вызывающий объект может определить причину сбоя, проверив параметр IoStatusBlock .

ZwCreateFile может возвращать STATUS_FILE_LOCK_CONFLICT в качестве возвращаемого значения или в элементе состояния структуры IO_STATUS_BLOCK , на которую указывает параметр IoStatusBlock . Это произойдет только в том случае, если файл журнала NTFS заполнен, и возникает ошибка, когда ZwCreateFile пытается справиться с этой ситуацией.

Замечания

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

После того как дескриптор, на который указывает FileHandle , больше не используется, драйвер должен вызвать ZwClose , чтобы закрыть его.

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

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

1. Полное имя пути, указанное в элементе ObjectName входного объекта ObjectAttributes.

2. Имя пути относительно файла каталога, представленного дескриптором в элементе RootDirectory входного объекта ObjectAttributes.

Установка определенных флагов в параметре DesiredAccess приводит к следующим эффектам:

• Чтобы вызывающий объект синхронизирул завершение ввода-вывода, ожидая возвращаемого файла FileHandle, необходимо задать флаг SYNCHRONIZE. В противном случае вызывающий объект, который является устройством или промежуточным драйвером, должен синхронизировать завершение ввода-вывода с помощью объекта события.

• Если вызывающий объект задает только флаги FILE_APPEND_DATA и СИНХРОНИЗАЦИИ, он может записывать только в конец файла, а любые сведения о смещении операций записи в файл игнорируются. Файл будет автоматически расширен по мере необходимости для этой операции.

• Установка флага FILE_WRITE_DATA для файла также позволяет вызывающей стороне записывать данные за пределы конца файла. Опять же, файл автоматически расширяется по мере необходимости.

• Если вызывающий объект задает только флаги FILE_EXECUTE и SYNCHRONIZE, он не может напрямую считывать или записывать данные в файл с помощью возвращаемого файла FileHandle. То есть все операции с файлом происходят через системный пейджер в ответ на инструкции и операции доступа к данным. Устройства и промежуточные драйверы не должны задавать флаг FILE_EXECUTE.

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

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

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

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

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

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

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

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

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

• Любой необязательный byteOffset , передаваемый в ZwReadFile или ZwWriteFile , должен иметь несколько размеров сектора.

• Длина, передаваемая в ZwReadFile или ZwWriteFile, должна быть неотъемлемой частью размера сектора. Обратите внимание, что указание операции чтения в буфер, длина которого точно равна размеру сектора, может привести к меньшему количеству значительных байтов, передаваемых в этот буфер, если конец файла был достигнут во время передачи.

• Буферы должны быть выровнены в соответствии с требованием выравнивания базового устройства. Чтобы получить эти сведения, вызовите ZwCreateFile , чтобы получить дескриптор для объекта файла, представляющего физическое устройство, и передайте его в ZwQueryInformationFile. Список значений FILE_XXX_ALIGNMENT системы см. в DEVICE_OBJECT.

• Вызовы ZwSetInformationFile с параметром FileInformationClass , заданным для FilePositionInformation , должны указывать смещение, которое является нескольким размером сектора.

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

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

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

В 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 завершается ошибкой, приложение, использующее этот флаг, должно закрыть его дескриптор после обнаружения сбоя запроса oplock.

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

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

1. Выдача запроса на создание с помощью 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.

2. Если запрос на создание выполнен успешно, запросите оплок.

3. Откройте другой дескриптор файла для выполнения операций ввода-вывода.

Шаг 3 делает это практическим только для фильтров оплоков. Маркер, открытый на шаге 3, может иметь DesiredAccess , содержащий максимум FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | СИНХРОНИЗАЦИЯ | READ_CONTROL и по-прежнему не прерывать блокировку фильтра. Тем не менее, любой DesiredAccess больше FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | СИНХРОНИЗАЦИЯ разорвит оплок уровня 1 или пакетной службы и сделает флаг FILE_RESERVE_OPFILTER бесполезным для этих типов оплоков.

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

Вызывающие файлы ZwCreateFile должны выполняться в IRQL = PASSIVE_LEVEL и с включенными специальными API ядра.

Если вызов этой функции происходит в пользовательском режиме, следует использовать имя NtCreateFile вместо ZwCreateFile.

Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

См. также

ACCESS_MASK

DEVICE_OBJECT

IO_STATUS_BLOCK

InitializeObjectAttributes

Использование версий nt и Zw подпрограмм собственных системных служб

ZwClose

ZwOpenFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile

  Оппортунистические блокировки

Повторная аналитика точек