Функция NtCreateFile (winternl.h)
Создает файл или каталог или открывает существующий файл, устройство, каталог или том.
Эта функция эквивалентна функции ZwCreateFile, описанной в комплекте драйверов Windows (WDK).
Синтаксис
__kernel_entry NTSTATUS NtCreateFile(
[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] PVOID EaBuffer,
[in] ULONG EaLength
);
Параметры
[out] FileHandle
Указатель на переменную, которая получает дескриптор файла, если вызов выполнен успешно.
[in] DesiredAccess
Значение ACCESS_MASK, которое выражает тип доступа, который вызывающий объект требует для файла или каталога. Набор системных флагов DesiredAccess определяет следующие определенные права доступа для объектов файлов.
Вызывающие объекты NtCreateFile могут указать одно или сочетание следующих значений, возможно, используя побитовое ИЛИ с дополнительными совместимыми флагами из списка флагов DesiredAccess для любого объекта файла, который не представляет файл каталога.
Значение FILE_GENERIC_EXECUTE не имеет значения для драйверов устройств и промежуточных драйверов.
STANDARD_RIGHTS_XXX являются предопределенными системными значениями, используемыми для обеспечения безопасности системных объектов.
Чтобы открыть или создать файл каталога, как показано в параметре CreateOptions, вызывающие NtCreateFile могут указать одно или сочетание следующих флагов, возможно, с помощью побитового ИЛИ с одним или несколькими совместимыми флагами из списка флагов DesiredAccess.
| Ценность | Значение |
|---|---|
|
Файлы в каталоге можно перечислить. |
|
Каталог можно пройти по пути: т. е. он может быть частью имени пути файла. |
[in] ObjectAttributes
Указатель на структуру, уже инициализированную с помощью InitializeObjectAttributes. Члены этой структуры для объекта файла включают следующие элементы.
| Ценность | Значение |
|---|---|
|
Указывает количество байтов ObjectAttributes предоставленных данных. Это значение должно быть по крайней мере sizeof(OBJECT_ATTRIBUTES). |
|
При необходимости задает дескриптор каталога, полученного при предыдущем вызове NtCreateFile. Если это значение равно |
|
Указывает на буферную строку Юникода, которая называет файл, который нужно создать или открыть. Это значение должно быть полной спецификацией файла или именем объекта устройства, если только это имя файла относительно каталога, указанного RootDirectory. Например, \Device\Floppy1\myfile.dat или \?? \B:\myfile.dat может быть полной спецификацией файла, при условии, что драйвер floppy и переопределенная файловая система уже загружены. Дополнительные сведения см. в разделе Имена файлов, пути и пространства имен. |
|
Представляет собой набор флагов, которые управляют атрибутами объекта файла. Это значение может быть равно нулю или OBJ_CASE_INSENSITIVE, указывающее, что код подстановки имен должен игнорировать регистр элемента ObjectName, а не выполнять поиск точного соответствия. Значение OBJ_INHERIT не относится к драйверам устройств и промежуточным драйверам. |
|
При необходимости указывает дескриптор безопасности, применяемый к файлу. Списки управления доступом, указанные таким дескриптором безопасности, применяются к файлу только при его создании. Если значение NULL при создании файла, ACL, помещенный в файл, зависит от файловой системы; большинство файловых систем распространяют некоторую часть такого ACL из родительского файла каталога в сочетании с ACL по умолчанию вызывающего объекта. Устройства и промежуточные драйверы могут задать для этого элемента значение NULL. |
|
Указывает права доступа, которые сервер должен быть предоставлен контексту безопасности клиента. Это значение не являетсяnull только при установке подключения к защищенному серверу, что позволяет вызывающему объекту контролировать, какие части контекста безопасности вызывающего объекта становятся доступными для сервера и разрешено ли олицетворение вызывающего сервера. |
[out] IoStatusBlock
Указатель на переменную, которая получает окончательное состояние завершения и сведения о запрошенной операции. При возвращении из NtCreateFileэлемент Information содержит одно из следующих значений:
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
Начальный размер выделения в байтах для файла. Ненулевое значение не действует, если файл не создается, перезаписывается или не заменяет его.
[in] FileAttributes
Атрибуты файла. Явно указанные атрибуты применяются только при создании, замене файла или перезаписи. По умолчанию это значение является FILE_ATTRIBUTE_NORMAL, которое можно переопределить сочетанием одного или нескольких флагов FILE_ATTRIBUTE_xxxx, определенных в Wdm.h и NtDdk.h. Список флагов, которые можно использовать с NtCreateFile, см. в разделе CreateFile.
[in] ShareAccess
Тип доступа к общей папке, который вызывающий объект хотел бы использовать в файле, как ноль, или как одно или сочетание следующих значений.
Дополнительные сведения см. в пакете SDK для Windows.
[in] CreateDisposition
Указывает, что делать, в зависимости от того, существует ли файл, как одно из следующих значений.
[in] CreateOptions
Параметры, применяемые при создании или открытии файла, в качестве совместимого сочетания следующих флагов.
[in] EaBuffer
Указатель на буфер EA, используемый для передачи расширенных атрибутов.
[in] EaLength
Длина буфера EA.
Возвращаемое значение
NtCreateFile возвращает STATUS_SUCCESS или соответствующее состояние ошибки. Если он возвращает состояние ошибки, вызывающий объект может найти дополнительные сведения о причине сбоя, проверив IoStatusBlock. Чтобы упростить эту проверку, приложение может использовать макросы NT_SUCCESS, NT_ERRORи NT_WARNING.
Замечания
Дескриптор, заданный NtCreateFile, можно использовать путем последующих вызовов для управления данными в файле или состоянии или атрибутах объекта файла.
Существует два альтернативных способа указать имя файла для создания или открытия с помощью NtCreateFile:
- Полное имя пути, предоставленное в элементе objectName
входных ObjectAttributes - Как имя пути относительно файла каталога, представленного дескриптором в RootDirectory элемент входных ObjectAttributes
Некоторые DesiredAccess флаги и сочетания флагов имеют следующие эффекты:
- Чтобы вызывающий объект синхронизировал завершение ввода-вывода, ожидая возвращаемого
FileHandle , необходимо задать флагSYNCHRONIZE. - Передача нуля в DesiredFlags недействительна.
- Если заданы только флаги FILE_APPEND_DATA и SYNCHRONIZE, вызывающий объект может записывать только в конец файла, а все сведения о смещениях записи в файл игнорируются. Однако файл автоматически расширяется при необходимости для этой операции записи.
- Установка флага FILE_WRITE_DATA для файла также позволяет записывать данные за пределы конца файла. Файл автоматически расширяется для этого типа записи, а также.
- Если заданы только флаги FILE_EXECUTE и SYNCHRONIZE, вызывающий объект не может напрямую считывать или записывать данные в файле с помощью возвращенной FileHandle, то есть все операции с файлом происходят через системный пейджер в ответ на инструкции и доступ к данным.
Параметр ShareAccess определяет, могут ли отдельные потоки получить доступ к одному файлу, возможно, одновременно. При условии, что оба средства открытия файлов имеют права доступа к файлу в указанном порядке, файл можно успешно открыть и предоставить общий доступ. Если исходный вызывающий объект NtCreateFile не указывает FILE_SHARE_READ, FILE_SHARE_WRITEили FILE_SHARE_DELETE, другие открытые операции не могут выполняться в файле; То есть исходный вызывающий объект получает монопольный доступ к файлу.
Чтобы общий файл был успешно открыт, запрошенный параметр DesiredAccess в файл должен быть совместим как с DesiredAccess, так и спецификации ShareAccess всех предыдущих открытий, которые еще не были выпущены с NtClose. То есть параметр DesiredAccess, указанный для NtCreateFile для данного файла, не должен конфликтовать с доступом, которые другие открытые элементы файла запрещены.
Значение CreateDispositionFILE_SUPERSEDE требует, чтобы вызывающий объект DELETE доступ к существующему объекту файла. Если это так, успешный вызов NtCreateFile с FILE_SUPERSEDE в существующем файле фактически удаляет этот файл, а затем повторно создает его. Это означает, что если файл уже открыт другим потоком, он открыл файл, указав параметр ShareAccess с набором флагов FILE_SHARE_DELETE.
Обратите внимание, что этот тип ликвидации соответствует стилю POSIX перезаписи файлов. Значения CreateDispositionFILE_OVERWRITE_IF и FILE_SUPERSEDE похожи. Если ZwCreateFile вызывается с существующим файлом и любой из этих значений CreateDisposition, файл заменяется.
Перезапись файла семантически эквивалентна операции замены, за исключением следующего:
- Вызывающий объект должен иметь доступ на запись к файлу, а не удалить доступ. Это означает, что, если файл уже открыт другим потоком, он открыл файл с флагом FILE_SHARE_WRITE, заданным во входном параметре ShareAccess.
- Указанные атрибуты файла логически являются ORed с теми, которые уже находятся в файле. Это означает, что если файл уже открыт другим потоком, последующий вызывающий объект NtCreateFile не может отключить существующие флаги FileAttributes, но может включить дополнительные флаги для того же файла. Обратите внимание, что этот стиль перезаписи файлов соответствует операционным системам MS-DOS, Windows 3.1 и OS/2.
Значение
Флаг CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING запрещает файловой системе выполнять любые промежуточные буферизации от имени вызывающего объекта. При указании этого значения некоторые ограничения для параметров вызывающего объекта размещаются в других подпрограммах NtXXXFile, включая следующие:
- Любые необязательные ByteOffset, передаваемые NtReadFile или Функции NtWriteFile должны быть неотъемлемой частью размера сектора.
- длина, передаваемая NtReadFile или NtWriteFile, должна быть неотъемлемой частью размера сектора. Обратите внимание, что указание операции чтения в буфер, длина которого точно равна размеру сектора, может привести к меньшему количеству значительных байтов, передаваемых в этот буфер, если конец файла был достигнут во время передачи.
- Буферы должны быть скорректированы в соответствии с требованием выравнивания базового устройства. Эти сведения можно получить путем вызова NtCreateFile для получения дескриптора для объекта файла, представляющего физическое устройство, а затем вызова NtQueryInformationFile с этим дескриптором. Список системных значений FILE_XXX_ALIGNMENT см. в документации по пакету SDK для Windows.
- Вызовы NtSetInformationFile с параметром FileInformationClass, равным FilePositionInformation, должны указывать смещение, которое является неотъемлемой частью размера сектора.
Если параметр createOptions
Флаг FILE_OPEN_REQUIRING_OPLOCK параметра CreateOptionsFILE_OPEN_REQUIRING_OPLOCK устраняет время между открытием файла и запросом оплока, который может позволить стороннему пользователю открывать файл, что приведет к нарушению общего доступа. Приложение может использовать флаг FILE_OPEN_REQUIRING_OPLOCK с NtCreateFile, а затем запросить любой oplock. Это гарантирует, что владелец oplock будет уведомлен о любом последующем открытом запросе, что приводит к нарушению общего доступа.
В Windows 7, если другие дескрипторы существуют в файле, когда приложение использует этот флаг, операция создания завершится ошибкой с STATUS_OPLOCK_NOT_GRANTED. Это ограничение больше не существует, начиная с Windows 8.
Если эта операция создания разорвит блокировку, которая уже существует в файле, то установка флага FILE_OPEN_REQUIRING_OPLOCK приведет к сбою операции создания с STATUS_CANNOT_BREAK_OPLOCK. Существующая операция создания не будет нарушена этой операцией создания.
Приложение, использующее этот флаг, должно запрашивать оплок после успешного вызова или все последующие попытки открытия файла будут заблокированы без использования обычной обработки оплока. Аналогичным образом, если этот вызов завершается успешно, но последующий запрос oplock завершается ошибкой, приложение, использующее этот флаг, должно закрыть его дескриптор после обнаружения сбоя запроса oplock.
Флаг FILE_RESERVE_OPFILTER параметра CreateOptions позволяет приложению запрашивать уровень 1, пакетную службу или фильтрацию, чтобы другие приложения не получали нарушения общего доступа. Однако в практическом плане FILE_RESERVE_OPFILTER полезно только для фильтров оплоков. Чтобы использовать его, необходимо выполнить следующие действия.
- Создайте запрос с CreateOptionsFILE_RESERVE_OPFILTER, DesiredAccess точно FILE_READ_ATTRIBUTESи ShareAccess точно
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE). Возможные сбои приведены следующим образом:- Если уже открытые дескрипторы, запрос создания завершается ошибкой STATUS_OPLOCK_NOT_GRANTED, а следующий запрошенный оплок также завершается ошибкой.
- Если вы открываете больше доступа, чем FILE_READ_ATTRIBUTES или меньше общего доступа, чем
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE), запрос завершается сбоем с STATUS_OPLOCK_NOT_GRANTED.
- Если запрос на создание выполнен успешно, запросите оплок.
- Откройте другой дескриптор файла для выполнения операций ввода-вывода.
(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 бесполезным для этих типов оплоков.
NTFS — это единственная файловая система Майкрософт, реализующая FILE_RESERVE_OPFILTER.
Дополнительные сведения об оплоках см. в разделе Оппортунистические блокировки.
Обратите внимание, что файл заголовка WDK NtDef.h необходим для многих определений констант, а также для макроса
Требования
| Требование | Ценность |
|---|---|
| целевая платформа | Виндоус |
| заголовка | winternl.h |
| библиотеки |
ntdll.lib |
| DLL | ntdll.dll |