Kernel-Mode Drivers: Windows 2000 DDK ZwCreateFile NTSTATUS ZwCreateFile( OUT PHANDLE FileHandle, IN ACCESS_MASK DesiredAccess, IN POBJECT_ATTRIBUTES ObjectAttributes, OUT PIO_STATUS_BLOCK IoStatusBlock, IN PLARGE_INTEGER AllocationSize OPTIONAL, IN ULONG FileAttributes, IN ULONG ShareAccess, IN ULONG CreateDisposition, IN ULONG CreateOptions, IN PVOID EaBuffer OPTIONAL, IN ULONG EaLength ); ZwCreateFile either causes a new file or directory to be created, or it opens an existing file, device, directory, or volume, giving the caller a handle for the file object. This handle can be used by subsequent calls to manipulate data within the file or the file object's state or attributes. For example, a driver might call this routine during initialization to open a file of microcode for its device.Parameters FileHandle Points to a variable that receives the file handle if the call is successful. DesiredAccess Specifies the type of access that the caller requires to the file or directory. The set of system-defined DesiredAccess flags determines the following specific access rights for file objects: DesiredAccess Flags Meaning DELETE The file can be deleted. FILE_READ_DATA Data can be read from the file. FILE_READ_ATTRIBUTES FileAttributes flags, described later, can be read. FILE_READ_EA Extended attributes associated with the file can be read. This flag is irrelevant to device and intermediate drivers. READ_CONTROL The access control list (ACL) and ownership information associated with the file can be read. FILE_WRITE_DATA Data can be written to the file. FILE_WRITE_ATTRIBUTES FileAttributes flags can be written. FILE_WRITE_EA Extended attributes (EAs) associated with the file can be written. This flag is irrelevant to device and intermediate drivers. FILE_APPEND_DATA Data can be appended to the file. WRITE_DAC The discretionary access control list (DACL) associated with the file can be written. WRITE_OWNER Ownership information associated with the file can be written. SYNCHRONIZE The returned FileHandle can be waited on to synchronize with the completion of an I/O operation. FILE_EXECUTE Data can be read into memory from the file using system paging I/O. This flag is irrelevant to device and intermediate drivers. Callers of ZwCreateFile can specify one or a combination of the following, possibly ORed with additional compatible flags from the preceding DesiredAccess Flags list, for any file object that does not represent a directory file: DesiredAccess to File Values Maps to DesiredAccess Flags GENERIC_READ STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, and FILE_READ_EA GENERIC_WRITE STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, and FILE_APPEND_DATA GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, and FILE_EXECUTE. This value is irrelevant to device and intermediate drivers. The STANDARD_RIGHTS_XXX are predefined system values used to enforce security on system objects. To open or create a directory file, as also indicated with the CreateOptions parameter, callers of ZwCreateFile can specify one or a combination of the following, possibly ORed with one or more compatible flags from the preceding DesiredAccess Flags list: DesiredAccess to Directory Values Meaning FILE_LIST_DIRECTORY Files in the directory can be listed. FILE_TRAVERSE The directory can be traversed: that is, it can be part of the pathname of a file. The FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE, and FILE_APPEND_DATA DesiredAccess flags are incompatible with creating or opening a directory file. ObjectAttributes Points to a structure already initialized with InitializeObjectAttributes. Members of this structure for a file object include the following: Member Value ULONG Length Specifies the number of bytes of ObjectAttributes data supplied. This value must be at least sizeof(OBJECT_ATTRIBUTES). PUNICODE_STRING ObjectName Points to a buffered Unicode string naming the file to be created or opened. This value must be a fully qualified file specification or the name of a device object, unless it is the name of a file relative to the directory specified by RootDirectory. For example, \Device\Floppy1\myfile.dat or \??\B:\myfile.dat could be the fully qualified file specification, provided that the floppy driver and overlying file system are already loaded. (Note: \?? replaces \DosDevices as the name of the Win32® object namespace. \DosDevices will still work, but \?? is translated faster by the object manager.) HANDLE RootDirectory Optionally specifies a handle to a directory obtained by a preceding call to ZwCreateFile. If this value is NULL, the ObjectName member must be a fully qualified file specification that includes the full path to the target file. If this value is nonNULL, the ObjectName member specifies a file name relative to this directory. PSECURITY_DESCRIPTOR SecurityDescriptor Optionally specifies a security descriptor to be applied to a file. ACLs specified by such a security descriptor are only applied to the file when it is created. If the value is NULL when a file is created, the ACL placed on the file is file-system-dependent; most file systems propagate some part of such an ACL from the parent directory file combined with the caller's default ACL. Device and intermediate drivers can set this member to NULL. PSECURITY_QUALITY_OF_SERVICE SecurityQualityOfService Specifies the access rights a server should be given to the client's security context. This value is nonNULL only when a connection to a protected server is established, allowing the caller to control which parts of the caller's security context are made available to the server and whether the server is allowed to impersonate the caller. Device and intermediate drivers usually set this member to NULL. ULONG Attributes Is a set of flags that controls the file object attributes. This value can be zero or OBJ_CASE_INSENSITIVE, which indicates that name-lookup code should ignore the case of ObjectName rather than performing an exact-match search. The value OBJ_INHERIT is irrelevant to device and intermediate drivers.
IoStatusBlock Points to a variable that receives the final completion status and information about the requested operation. On return from ZwCreateFile, the Information member contains one of the following values: FILE_CREATED FILE_OPENED FILE_OVERWRITTEN FILE_SUPERSEDED FILE_EXISTS FILE_DOES_NOT_EXIST AllocationSize Optionally specifies the initial allocation size in bytes for the file. A nonzero value has no effect unless the file is being created, overwritten, or superseded. FileAttributes Explicitly specified attributes are applied only when the file is created, superseded, or, in some cases, overwritten. By default, this value is FILE_ATTRIBUTE_NORMAL, which can be overridden by any other flag or by an ORed combination of compatible flags. Possible FileAttributes flags include the following: FileAttributes Flags Meaning FILE_ATTRIBUTE_NORMAL A file with standard attributes should be created. FILE_ATTRIBUTE_READONLY A read-only file should be created. FILE_ATTRIBUTE_HIDDEN A hidden file should be created. FILE_ATTRIBUTE_SYSTEM A system file should be created. FILE_ATTRIBUTE_ARCHIVE The file should be ed so that it will be archived. FILE_ATTRIBUTE_TEMPORARY A temporary file should be created. FILE_ATTRIBUTE_ATOMIC_WRITE An atomic-write file should be created. This flag is irrelevant to device and intermediate drivers. FILE_ATTRIBUTE_XACTION_WRITE A transaction-write file should be created. This flag is irrelevant to device and intermediate drivers. ShareAccess Specifies the type of share access that the caller would like to the file, as zero, or as one or a combination of the following: ShareAccess Flags Meaning FILE_SHARE_READ The file can be opened for read access by other threads' calls to ZwCreateFile. FILE_SHARE_WRITE The file can be opened for write access by other threads' calls to ZwCreateFile. FILE_SHARE_DELETE The file can be opened for delete access by other threads' calls to ZwCreateFile. Device and intermediate drivers usually set ShareAccess to zero, which gives the caller exclusive access to the open file. CreateDisposition Specifies what to do, depending on whether the file already exists, as one of the following: CreateDispostion Values Meaning FILE_SUPERSEDE If the file already exists, replace it with the given file. If it does not, create the given file. FILE_CREATE If the file already exists, fail the request and do not create or open the given file. If it does not, create the given file. FILE_OPEN If the file already exists, open it instead of creating a new file. If it does not, fail the request and do not create a new file. FILE_OPEN_IF If the file already exists, open it. If it does not, create the given file. FILE_OVERWRITE If the file already exists, open it and overwrite it. If it does not, fail the request. FILE_OVERWRITE_IF If the file already exists, open it and overwrite it. If it does not, create the given file. CreateOptions Specifies the options to be applied when creating or opening the file, as a compatible combination of the following flags: CreateOptions Flags Meaning FILE_DIRECTORY_FILE The file being created or opened is a directory file. With this flag, the CreateDisposition parameter must be set to one of FILE_CREATE, FILE_OPEN, or FILE_OPEN_IF. With this flag, other compatible CreateOptions flags include only the following: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO _NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT, and FILE_OPEN_BY_FILE_ID. FILE_NON_DIRECTORY_FILE The file being opened must not be a directory file or this call will fail. The file object being opened can represent a data file, a logical, virtual, or physical device, or a volume. FILE_WRITE_THROUGH System services, FSDs, and drivers that write data to the file must actually transfer the data into the file before any requested write operation is considered complete. This flag is automatically set if the CreateOptions flag FILE_NO_INTERMEDIATE _BUFFERING is set. FILE_SEQUENTIAL_ONLY All accesses to the file will be sequential. FILE_RANDOM_ACCESS Accesses to the file can be random, so no sequential read-ahead operations should be performed on the file by FSDs or the system. FILE_NO_INTERMEDIATE_BUFFERING The file cannot be cached or buffered in a driver's internal buffers. This flag is incompatible with the DesiredAccess FILE_APPEND_DATA flag. FILE_SYNCHRONOUS_IO_ALERT All operations on the file are performed synchronously. Any wait on behalf of the caller is subject to premature termination from alerts. This flag also causes the I/O system to maintain the file position context. If this flag is set, the DesiredAccess SYNCHRONIZE flag also must be set. FILE_SYNCHRONOUS_IO_NONALERT All operations on the file are performed synchronously. Waits in the system to synchronize I/O queueing and completion are not subject to alerts. This flag also causes the I/O system to maintain the file position context. If this flag is set, the DesiredAccess SYNCHRONIZE flag also must be set. FILE_CREATE_TREE_CONNECTION Create a tree connection for this file in order to open it over the network. This flag is irrelevant to device and intermediate drivers. FILE_COMPLETE_IF_OPLOCKED Complete this operation immediately with an alternate success code if the target file is oplocked, rather than blocking the caller's thread. If the file is oplocked, another caller already has access to the file over the network. This flag is irrelevant to device and intermediate drivers. FILE_NO_EA_KNOWLEDGE If the extended attributes on an existing file being opened indicate that the caller must understand EAs to properly interpret the file, fail this request because the caller does not understand how to deal with EAs. Device and intermediate drivers can ignore this flag. FILE_DELETE_ON_CLOSE Delete the file when the last handle to it is is passed to ZwClose. FILE_OPEN_BY_FILE_ID The file name contains the name of a device and a 64-bit ID to be used to open the file. This flag is irrelevant to device and intermediate drivers. FILE_OPEN_FOR_BACKUP_INTENT The file is being opened for backup intent, hence, the system should check for certain access rights and grant the caller the appropriate accesses to the file before checking the input DesiredAccess against the file's security descriptor. This flag is irrelevant to device and intermediate drivers. EaBuffer For device and intermediate drivers, this parameter must be a NULL pointer. EaLength For device and intermediate drivers, this parameter must be zero. Include wdm.h or ntddk.h Return Value ZwCreateFile either returns STATUS_SUCCESS or an appropriate error status. If it returns an error status, the caller can find more information about the cause of the failure by checking the IoStatusBlock.Comments There are two alternate ways to specify the name of the file to be created or opened with ZwCreateFile: As a fully qualified pathname, supplied in the ObjectName member of the input ObjectAttributes As pathname relative to the directory file represented by the handle in the RootDirectory member of the input ObjectAttributes Certain DesiredAccess flags and combinations of flags have the following effects:
For a caller to synchronize an I/O completion by waiting on the returned FileHandle, the SYNCHRONIZE flag must be set. Otherwise, a caller that is a device or intermediate driver must synchronize an I/O completion by using an event object. If only the FILE_APPEND_DATA and SYNCHRONIZE flags are set, the caller can write only to the end of the file, and any offset information on writes to the file is ignored. However, the file will automatically be extended as necessary for this type of write operation. Setting the FILE_WRITE_DATA flag for a file also allows writes beyond the end of the file to occur. The file is automatically extended for this type of write, as well. If only the FILE_EXECUTE and SYNCHRONIZE flags are set, the caller cannot directly read or write any data in the file using the returned FileHandle: that is, all operations on the file occur through the system pager in response to instruction and data accesses. Device and intermediate drivers should not set the FILE_EXECUTE flag in DesiredAccess. The ShareAccess parameter determines whether separate threads can access the same file, possibly simultaneously. Provided that both file openers have the privilege to access a file in the specified manner, the file can be successfully opened and shared. If the original caller of ZwCreateFile does not specify FILE_SHARE_READ, FILE_SHARE_WRITE, or FILE_SHARE_DELETE, no other open operations can be performed on the file: that is, the original caller is given exclusive access to the file.In order for a shared file to be successfully opened, the requested DesiredAccess to the file must be compatible with both the DesiredAccess and ShareAccess specifications of all preceding opens that have not yet been released with ZwClose. That is, the DesiredAccess specified to ZwCreateFile for a given file must not conflict with the accesses that other openers of the file have disallowed.The CreateDispostion value FILE_SUPERSEDE requires that the caller have DELETE access to a existing file object. If so, a successful call to ZwCreateFile with FILE_SUPERSEDE on an existing file effectively deletes that file, and then recreates it. This implies that, if the file has already been opened by another thread, it opened the file by specifying a ShareAccess parameter with the FILE_SHARE_DELETE flag set. Note that this type of disposition is consistent with the POSIX style of overwriting files.The CreateDisposition values FILE_OVERWRITE_IF and FILE_SUPERSEDE are similar. If ZwCreateFile is called with a existing file and either of these CreateDisposition values, the file will be replaced.Overwriting a file is semantically equivalent to a supersede operation, except for the following: The caller must have write access to the file, rather than delete access. This implies that, if the file has already been opened by another thread, it opened the file with the FILE_SHARE_WRITE flag set in the input ShareAccess. The specified file attributes are logically ORed with those already on the file. This implies that, if the file has already been opened by another thread, a subsequent caller of ZwCreateFile cannot disable existing FileAttributes flags but can enable additional flags for the same file. Note that this style of overwriting files is consistent with MS-DOS®, Windows® 3.1, and with OS/2. The CreateOptions FILE_DIRECTORY_FILE value specifies that the file to be created or opened is a directory file. When a directory file is created, the file system creates an appropriate structure on the disk to represent an empty directory for that particular file system's on-disk structure. If this option was specified and the given file to be opened is not a directory file, or if the caller specified an inconsistent CreateOptions or CreateDispostion value, the call to ZwCreateFile will fail.The CreateOptions FILE_NO_INTERMEDIATE_BUFFERING flag prevents the file system from performing any intermediate buffering on behalf of the caller. Specifying this value places certain restrictions on the caller's parameters to other Zw..File routines, including the following: Any optional ByteOffset passed to ZwReadFile or ZwWriteFile must be an integral of the sector size. The Length passed to ZwReadFile or ZwWriteFile, must be an integral of the sector size. Note that specifying a read operation to a buffer whose length is exactly the sector size might result in a lesser number of significant bytes being transferred to that buffer if the end of the file was reached during the transfer. Buffers must be aligned in accordance with the alignment requirement of the underlying device. This information can be obtained by calling ZwCreateFile to get a handle for the file object that represents the physical device, and, then, calling ZwQueryInformationFile with that handle. For a list of the system FILE_XXX_ALIGNMENT values, see DEVICE_OBJECT in Chapter 12. Calls to ZwSetInformationFile with the FileInformationClass parameter set to FilePositionInformation must specify an offset that is an integral of the sector size. The CreateOptions FILE_SYNCHRONOUS_IO_ALERT and FILE_SYNCHRONOUS_IO_NONALERT, which are mutually exclusive as their names suggest, specify that all I/O operations on the file are to be synchronous as long as they occur through the file object referred to by the returned FileHandle. All I/O on such a file is serialized across all threads using the returned handle. With either of these CreateOptions, the DesiredAccess SYNCHRONIZE flag must be set so that the I/O Manager will use the file object as a synchronization object. With either of these CreateOptions set, the I/O Manager maintains the "file position context" for the file object, an internal, current file position offset. This offset can be used in calls to ZwReadFile and ZwWriteFile. Its position also can be queried or set with ZwQueryInformationFile and ZwSetInformationFile.Callers of ZwCreateFile must be running at IRQL PASSIVE_LEVEL.See Also InitializeObjectAttributes, DEVICE_OBJECT, IO_STATUS_BLOCK, ZwClose, ZwReadFile, ZwQueryInformationFile, ZwSetInformationFile, ZwWriteFile Built on Wednesday, June 28, 2000
fp = fopen("c:\\test.txt","r");
if(fp == NULL)
AfxMessageBox("文件不存在");
ZwCreateFile
NTSTATUS
ZwCreateFile(
OUT PHANDLE FileHandle,
IN ACCESS_MASK DesiredAccess,
IN POBJECT_ATTRIBUTES ObjectAttributes,
OUT PIO_STATUS_BLOCK IoStatusBlock,
IN PLARGE_INTEGER AllocationSize OPTIONAL,
IN ULONG FileAttributes,
IN ULONG ShareAccess,
IN ULONG CreateDisposition,
IN ULONG CreateOptions,
IN PVOID EaBuffer OPTIONAL,
IN ULONG EaLength
);
ZwCreateFile either causes a new file or directory to be created, or it opens an existing file, device, directory, or volume, giving the caller a handle for the file object. This handle can be used by subsequent calls to manipulate data within the file or the file object's state or attributes. For example, a driver might call this routine during initialization to open a file of microcode for its device.Parameters
FileHandle
Points to a variable that receives the file handle if the call is successful.
DesiredAccess
Specifies the type of access that the caller requires to the file or directory. The set of system-defined DesiredAccess flags determines the following specific access rights for file objects: DesiredAccess Flags Meaning
DELETE The file can be deleted.
FILE_READ_DATA Data can be read from the file.
FILE_READ_ATTRIBUTES FileAttributes flags, described later, can be read.
FILE_READ_EA Extended attributes associated with the file can be read. This flag is irrelevant to device and intermediate drivers.
READ_CONTROL The access control list (ACL) and ownership information associated with the file can be read.
FILE_WRITE_DATA Data can be written to the file.
FILE_WRITE_ATTRIBUTES FileAttributes flags can be written.
FILE_WRITE_EA Extended attributes (EAs) associated with the file can be written. This flag is irrelevant to device and intermediate drivers.
FILE_APPEND_DATA Data can be appended to the file.
WRITE_DAC The discretionary access control list (DACL) associated with the file can be written.
WRITE_OWNER Ownership information associated with the file can be written.
SYNCHRONIZE The returned FileHandle can be waited on to synchronize with the completion of an I/O operation.
FILE_EXECUTE Data can be read into memory from the file using system paging I/O. This flag is irrelevant to device and intermediate drivers.
Callers of ZwCreateFile can specify one or a combination of the following, possibly ORed with additional compatible flags from the preceding DesiredAccess Flags list, for any file object that does not represent a directory file: DesiredAccess to File Values Maps to DesiredAccess Flags
GENERIC_READ STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, and FILE_READ_EA
GENERIC_WRITE STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, and FILE_APPEND_DATA
GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, and FILE_EXECUTE. This value is irrelevant to device and intermediate drivers. The STANDARD_RIGHTS_XXX are predefined system values used to enforce security on system objects. To open or create a directory file, as also indicated with the CreateOptions parameter, callers of ZwCreateFile can specify one or a combination of the following, possibly ORed with one or more compatible flags from the preceding DesiredAccess Flags list: DesiredAccess to Directory Values Meaning
FILE_LIST_DIRECTORY Files in the directory can be listed.
FILE_TRAVERSE The directory can be traversed: that is, it can be part of the pathname of a file. The FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE, and FILE_APPEND_DATA DesiredAccess flags are incompatible with creating or opening a directory file. ObjectAttributes
Points to a structure already initialized with InitializeObjectAttributes. Members of this structure for a file object include the following: Member Value
ULONG Length
Specifies the number of bytes of ObjectAttributes data supplied. This value must be at least sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName
Points to a buffered Unicode string naming the file to be created or opened. This value must be a fully qualified file specification or the name of a device object, unless it is the name of a file relative to the directory specified by RootDirectory. For example, \Device\Floppy1\myfile.dat or \??\B:\myfile.dat could be the fully qualified file specification, provided that the floppy driver and overlying file system are already loaded. (Note: \?? replaces \DosDevices as the name of the Win32® object namespace. \DosDevices will still work, but \?? is translated faster by the object manager.)
HANDLE RootDirectory
Optionally specifies a handle to a directory obtained by a preceding call to ZwCreateFile. If this value is NULL, the ObjectName member must be a fully qualified file specification that includes the full path to the target file. If this value is nonNULL, the ObjectName member specifies a file name relative to this directory.
PSECURITY_DESCRIPTOR SecurityDescriptor
Optionally specifies a security descriptor to be applied to a file. ACLs specified by such a security descriptor are only applied to the file when it is created. If the value is NULL when a file is created, the ACL placed on the file is file-system-dependent; most file systems propagate some part of such an ACL from the parent directory file combined with the caller's default ACL. Device and intermediate drivers can set this member to NULL.
PSECURITY_QUALITY_OF_SERVICE SecurityQualityOfService
Specifies the access rights a server should be given to the client's security context. This value is nonNULL only when a connection to a protected server is established, allowing the caller to control which parts of the caller's security context are made available to the server and whether the server is allowed to impersonate the caller. Device and intermediate drivers usually set this member to NULL.
ULONG Attributes
Is a set of flags that controls the file object attributes. This value can be zero or OBJ_CASE_INSENSITIVE, which indicates that name-lookup code should ignore the case of ObjectName rather than performing an exact-match search. The value OBJ_INHERIT is irrelevant to device and intermediate drivers.
Points to a variable that receives the final completion status and information about the requested operation. On return from ZwCreateFile, the Information member contains one of the following values:
FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST AllocationSize
Optionally specifies the initial allocation size in bytes for the file. A nonzero value has no effect unless the file is being created, overwritten, or superseded.
FileAttributes
Explicitly specified attributes are applied only when the file is created, superseded, or, in some cases, overwritten. By default, this value is FILE_ATTRIBUTE_NORMAL, which can be overridden by any other flag or by an ORed combination of compatible flags. Possible FileAttributes flags include the following: FileAttributes Flags Meaning
FILE_ATTRIBUTE_NORMAL A file with standard attributes should be created.
FILE_ATTRIBUTE_READONLY A read-only file should be created.
FILE_ATTRIBUTE_HIDDEN A hidden file should be created.
FILE_ATTRIBUTE_SYSTEM A system file should be created.
FILE_ATTRIBUTE_ARCHIVE The file should be ed so that it will be archived.
FILE_ATTRIBUTE_TEMPORARY A temporary file should be created.
FILE_ATTRIBUTE_ATOMIC_WRITE An atomic-write file should be created. This flag is irrelevant to device and intermediate drivers.
FILE_ATTRIBUTE_XACTION_WRITE A transaction-write file should be created. This flag is irrelevant to device and intermediate drivers.
ShareAccess
Specifies the type of share access that the caller would like to the file, as zero, or as one or a combination of the following: ShareAccess Flags Meaning
FILE_SHARE_READ The file can be opened for read access by other threads' calls to ZwCreateFile.
FILE_SHARE_WRITE The file can be opened for write access by other threads' calls to ZwCreateFile.
FILE_SHARE_DELETE The file can be opened for delete access by other threads' calls to ZwCreateFile.
Device and intermediate drivers usually set ShareAccess to zero, which gives the caller exclusive access to the open file. CreateDisposition
Specifies what to do, depending on whether the file already exists, as one of the following: CreateDispostion Values Meaning
FILE_SUPERSEDE If the file already exists, replace it with the given file. If it does not, create the given file.
FILE_CREATE If the file already exists, fail the request and do not create or open the given file. If it does not, create the given file.
FILE_OPEN If the file already exists, open it instead of creating a new file. If it does not, fail the request and do not create a new file.
FILE_OPEN_IF If the file already exists, open it. If it does not, create the given file.
FILE_OVERWRITE If the file already exists, open it and overwrite it. If it does not, fail the request.
FILE_OVERWRITE_IF If the file already exists, open it and overwrite it. If it does not, create the given file.
CreateOptions
Specifies the options to be applied when creating or opening the file, as a compatible combination of the following flags: CreateOptions Flags Meaning
FILE_DIRECTORY_FILE The file being created or opened is a directory file. With this flag, the CreateDisposition parameter must be set to one of FILE_CREATE, FILE_OPEN, or FILE_OPEN_IF. With this flag, other compatible CreateOptions flags include only the following: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO
_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT, and FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE The file being opened must not be a directory file or this call will fail. The file object being opened can represent a data file, a logical, virtual, or physical device, or a volume.
FILE_WRITE_THROUGH System services, FSDs, and drivers that write data to the file must actually transfer the data into the file before any requested write operation is considered complete. This flag is automatically set if the CreateOptions flag FILE_NO_INTERMEDIATE
_BUFFERING is set.
FILE_SEQUENTIAL_ONLY All accesses to the file will be sequential.
FILE_RANDOM_ACCESS Accesses to the file can be random, so no sequential read-ahead operations should be performed on the file by FSDs or the system.
FILE_NO_INTERMEDIATE_BUFFERING The file cannot be cached or buffered in a driver's internal buffers. This flag is incompatible with the DesiredAccess FILE_APPEND_DATA flag.
FILE_SYNCHRONOUS_IO_ALERT All operations on the file are performed synchronously. Any wait on behalf of the caller is subject to premature termination from alerts. This flag also causes the I/O system to maintain the file position context. If this flag is set, the DesiredAccess SYNCHRONIZE flag also must be set.
FILE_SYNCHRONOUS_IO_NONALERT All operations on the file are performed synchronously. Waits in the system to synchronize I/O queueing and completion are not subject to alerts. This flag also causes the I/O system to maintain the file position context. If this flag is set, the DesiredAccess SYNCHRONIZE flag also must be set.
FILE_CREATE_TREE_CONNECTION Create a tree connection for this file in order to open it over the network. This flag is irrelevant to device and intermediate drivers.
FILE_COMPLETE_IF_OPLOCKED Complete this operation immediately with an alternate success code if the target file is oplocked, rather than blocking the caller's thread. If the file is oplocked, another caller already has access to the file over the network. This flag is irrelevant to device and intermediate drivers.
FILE_NO_EA_KNOWLEDGE If the extended attributes on an existing file being opened indicate that the caller must understand EAs to properly interpret the file, fail this request because the caller does not understand how to deal with EAs. Device and intermediate drivers can ignore this flag.
FILE_DELETE_ON_CLOSE Delete the file when the last handle to it is is passed to ZwClose.
FILE_OPEN_BY_FILE_ID The file name contains the name of a device and a 64-bit ID to be used to open the file. This flag is irrelevant to device and intermediate drivers.
FILE_OPEN_FOR_BACKUP_INTENT The file is being opened for backup intent, hence, the system should check for certain access rights and grant the caller the appropriate accesses to the file before checking the input DesiredAccess against the file's security descriptor. This flag is irrelevant to device and intermediate drivers.
EaBuffer
For device and intermediate drivers, this parameter must be a NULL pointer.
EaLength
For device and intermediate drivers, this parameter must be zero.
Include
wdm.h or ntddk.h Return Value
ZwCreateFile either returns STATUS_SUCCESS or an appropriate error status. If it returns an error status, the caller can find more information about the cause of the failure by checking the IoStatusBlock.Comments
There are two alternate ways to specify the name of the file to be created or opened with ZwCreateFile: As a fully qualified pathname, supplied in the ObjectName member of the input ObjectAttributes
As pathname relative to the directory file represented by the handle in the RootDirectory member of the input ObjectAttributes
Certain DesiredAccess flags and combinations of flags have the following effects:
If only the FILE_APPEND_DATA and SYNCHRONIZE flags are set, the caller can write only to the end of the file, and any offset information on writes to the file is ignored. However, the file will automatically be extended as necessary for this type of write operation.
Setting the FILE_WRITE_DATA flag for a file also allows writes beyond the end of the file to occur. The file is automatically extended for this type of write, as well.
If only the FILE_EXECUTE and SYNCHRONIZE flags are set, the caller cannot directly read or write any data in the file using the returned FileHandle: that is, all operations on the file occur through the system pager in response to instruction and data accesses. Device and intermediate drivers should not set the FILE_EXECUTE flag in DesiredAccess.
The ShareAccess parameter determines whether separate threads can access the same file, possibly simultaneously. Provided that both file openers have the privilege to access a file in the specified manner, the file can be successfully opened and shared. If the original caller of ZwCreateFile does not specify FILE_SHARE_READ, FILE_SHARE_WRITE, or FILE_SHARE_DELETE, no other open operations can be performed on the file: that is, the original caller is given exclusive access to the file.In order for a shared file to be successfully opened, the requested DesiredAccess to the file must be compatible with both the DesiredAccess and ShareAccess specifications of all preceding opens that have not yet been released with ZwClose. That is, the DesiredAccess specified to ZwCreateFile for a given file must not conflict with the accesses that other openers of the file have disallowed.The CreateDispostion value FILE_SUPERSEDE requires that the caller have DELETE access to a existing file object. If so, a successful call to ZwCreateFile with FILE_SUPERSEDE on an existing file effectively deletes that file, and then recreates it. This implies that, if the file has already been opened by another thread, it opened the file by specifying a ShareAccess parameter with the FILE_SHARE_DELETE flag set. Note that this type of disposition is consistent with the POSIX style of overwriting files.The CreateDisposition values FILE_OVERWRITE_IF and FILE_SUPERSEDE are similar. If ZwCreateFile is called with a existing file and either of these CreateDisposition values, the file will be replaced.Overwriting a file is semantically equivalent to a supersede operation, except for the following: The caller must have write access to the file, rather than delete access. This implies that, if the file has already been opened by another thread, it opened the file with the FILE_SHARE_WRITE flag set in the input ShareAccess.
The specified file attributes are logically ORed with those already on the file. This implies that, if the file has already been opened by another thread, a subsequent caller of ZwCreateFile cannot disable existing FileAttributes flags but can enable additional flags for the same file. Note that this style of overwriting files is consistent with MS-DOS®, Windows® 3.1, and with OS/2.
The CreateOptions FILE_DIRECTORY_FILE value specifies that the file to be created or opened is a directory file. When a directory file is created, the file system creates an appropriate structure on the disk to represent an empty directory for that particular file system's on-disk structure. If this option was specified and the given file to be opened is not a directory file, or if the caller specified an inconsistent CreateOptions or CreateDispostion value, the call to ZwCreateFile will fail.The CreateOptions FILE_NO_INTERMEDIATE_BUFFERING flag prevents the file system from performing any intermediate buffering on behalf of the caller. Specifying this value places certain restrictions on the caller's parameters to other Zw..File routines, including the following: Any optional ByteOffset passed to ZwReadFile or ZwWriteFile must be an integral of the sector size.
The Length passed to ZwReadFile or ZwWriteFile, must be an integral of the sector size. Note that specifying a read operation to a buffer whose length is exactly the sector size might result in a lesser number of significant bytes being transferred to that buffer if the end of the file was reached during the transfer.
Buffers must be aligned in accordance with the alignment requirement of the underlying device. This information can be obtained by calling ZwCreateFile to get a handle for the file object that represents the physical device, and, then, calling ZwQueryInformationFile with that handle. For a list of the system FILE_XXX_ALIGNMENT values, see DEVICE_OBJECT in Chapter 12.
Calls to ZwSetInformationFile with the FileInformationClass parameter set to FilePositionInformation must specify an offset that is an integral of the sector size.
The CreateOptions FILE_SYNCHRONOUS_IO_ALERT and FILE_SYNCHRONOUS_IO_NONALERT, which are mutually exclusive as their names suggest, specify that all I/O operations on the file are to be synchronous as long as they occur through the file object referred to by the returned FileHandle. All I/O on such a file is serialized across all threads using the returned handle. With either of these CreateOptions, the DesiredAccess SYNCHRONIZE flag must be set so that the I/O Manager will use the file object as a synchronization object. With either of these CreateOptions set, the I/O Manager maintains the "file position context" for the file object, an internal, current file position offset. This offset can be used in calls to ZwReadFile and ZwWriteFile. Its position also can be queried or set with ZwQueryInformationFile and ZwSetInformationFile.Callers of ZwCreateFile must be running at IRQL PASSIVE_LEVEL.See Also
InitializeObjectAttributes, DEVICE_OBJECT, IO_STATUS_BLOCK, ZwClose, ZwReadFile, ZwQueryInformationFile, ZwSetInformationFile, ZwWriteFile Built on Wednesday, June 28, 2000