The IoCreateFile routine 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.
NTKERNELAPI NTSTATUS IoCreateFile( PHANDLE FileHandle, ACCESS_MASK DesiredAccess, POBJECT_ATTRIBUTES ObjectAttributes, PIO_STATUS_BLOCK IoStatusBlock, PLARGE_INTEGER AllocationSize, ULONG FileAttributes, ULONG ShareAccess, ULONG Disposition, ULONG CreateOptions, PVOID EaBuffer, ULONG EaLength, CREATE_FILE_TYPE CreateFileType, PVOID InternalParameters, ULONG Options );
A pointer to a variable that receives the file handle if the call is successful. The driver must close the handle with ZwClose once the handle is no longer in use.
A pointer to a structure that specifies the object's attributes, which has already been initialized with InitializeObjectAttributes. If the caller is not running in the system process context, it must set the OBJ_KERNEL_HANDLE attribute for ObjectAttributes.
A pointer to a variable that receives the final completion status and information about the requested operation. On return from IoCreateFile, the Information member contains one of the following values:
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.
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 an ORed combination of one or more FILE_ATTRIBUTE_XXX flags, which are defined in Wdm.h. For a list of flags that can be used with IoCreateFile, see CreateFile in the Microsoft Windows SDK documentation.
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:
|FILE_SHARE_READ||The file can be opened for read access by other threads' calls to IoCreateFile.|
|FILE_SHARE_WRITE||The file can be opened for write access by other threads' calls to IoCreateFile.|
|FILE_SHARE_DELETE||The file can be opened for delete access by other threads' calls to IoCreateFile.|
Device and intermediate drivers usually set ShareAccess to zero, which gives the caller exclusive access to the open file.
Specifies what to do, depending on whether the file already exists, as one of the following:
|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.|
Specifies the options to be applied when creating or opening the file, as a compatible combination of the following flags:
|FILE_DIRECTORY_FILE||The file being created or opened is a directory file. With this flag, the Disposition 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, file system drivers (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.|
|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 queuing 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_OPEN_REPARSE_POINT||Open a file with a reparse point and bypass normal reparse point processing for the file. For more information, see the following Remarks section.|
|FILE_DELETE_ON_CLOSE||Delete the file when the last handle to it is passed to ZwClose.|
|FILE_OPEN_BY_FILE_ID||The file name specified in the ObjectAttributes parameter includes the 8-byte file reference number for the file. This number is assigned by the file system and is file-system-specific. If the file is a reparse point, the file name also includes the name of a device. Note: The FAT file system does not support FILE_OPEN_BY_FILE_ID.|
|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.|
The file is being opened and an opportunistic lock (oplock) on the file is being requested as a single atomic operation. The file system checks for oplocks before it performs the create operation, and the create operation will fail with a return code of STATUS_CANNOT_BREAK_OPLOCK if the create operation would break an existing oplock.
Note The FILE_OPEN_REQUIRING_OPLOCK flag is available in Windows 7, Windows Server 2008 R2, and later Windows operating systems.
|FILE_RESERVE_OPFILTER||This flag allows an application to request a filter opportunistic lock (oplock) to prevent other applications from getting share violations. If there are already open handles, the create request will fail with STATUS_OPLOCK_NOT_GRANTED. For more information, see the following Remarks section.|
For device and intermediate drivers, this parameter must be a NULL pointer.
For device and intermediate drivers, this parameter must be zero.
Drivers must set this parameter to CreateFileTypeNone.
Drivers must set this parameter to NULL.
Specifies options to be used during the creation of the create request. These options can be from the following list:
|IO_NO_PARAMETER_CHECKING||Indicates that the parameters for this call should not be validated before attempting to issue the create request. Driver writers should use this flag with caution as certain invalid parameters can cause a system failure. For more information, see Remarks.|
|IO_FORCE_ACCESS_CHECK||Indicates that the I/O manager must check the operation against the file's security descriptor.|
|IO_STOP_ON_SYMLINK||The I/O manager or the file system will return STATUS_STOPPED_ON_SYMLINK if a symbolic link is encountered while opening or creating the file.|
|IO_OPEN_TARGET_DIRECTORY||Open the file's parent directory.|
IoCreateFile either returns STATUS_SUCCESS or an appropriate error status. If it returns an error status, the caller can find additional information about the cause of the failure by checking the IoStatusBlock.
- 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
- For a caller to synchronize an I/O completion by waiting for 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 about 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 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 IoCreateFile cannot disable existing FileAttributes flags but can enable additional flags for the same file.
- 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 IoCreateFile 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.
- Calls to ZwSetInformationFile with the FileInformationClass parameter set to FilePositionInformation must specify an offset that is an integral of the sector size.
Issue a create request with CreateOptions of FILE_RESERVE_OPFILTER, DesiredAccess of exactly FILE_READ_ATTRIBUTES, and ShareAccess of exactly FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- If there are already open handles, the create request fails with STATUS_OPLOCK_NOT_GRANTED, and the next requested oplock also fails.
- If you open with more access or less sharing will also cause a failure of STATUS_OPLOCK_NOT_GRANTED.
- If the create request succeeds, request an oplock.
- Open another handle to the file to do I/O.
InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);
|Windows version||Available starting with Windows 2000.|
|Header||wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)|
|DDI compliance rules||IrqlIoPassive4, PowerIrpDDis, HwStorPortProhibitedDDIs|