Creating and Opening Files
The CreateFile function can create a new file or open an existing file. You must specify the file name, creation instructions, and other attributes. When an application creates a new file, the operating system adds it to the specified directory.
The operating system assigns a unique identifier, called a handle, to each file that is opened or created using CreateFile. An application can use this handle with functions that read from, write to, and describe the file. It is valid until all references to that handle are closed. When an application starts, it inherits all open handles from the process that started it if the handles were created as inheritable.
An application should check the value of the handle returned by CreateFile before attempting to use the handle to access the file. If an error occurs, the handle value will be INVALID_HANDLE_VALUE and the application can use the GetLastError function for extended error information.
When an application uses CreateFile, it must use the dwDesiredAccess parameter to specify whether it intends to read from the file, write to the file, both read and write, or neither. This is known as requesting an access mode. The application must also use the dwCreationDisposition parameter to specify what action to take if the file already exists, known as the creation disposition. For example, an application can call CreateFile with dwCreationDisposition set to CREATE_ALWAYS to always create a new file, even if a file of the same name already exists (thus overwriting the existing file). Whether this succeeds or not depends on factors such as the previous file's attributes and security settings (see the following sections for more information).
An application also uses CreateFile to specify whether it wants to share the file for reading, writing, both, or neither. This is known as the sharing mode. An open file that is not shared (dwShareMode set to zero) cannot be opened again, either by the application that opened it or by another application, until its handle has been closed. This is also referred to as exclusive access.
When a process uses CreateFile to attempt to open a file that has already been opened in a sharing mode (dwShareMode set to a valid nonzero value), the system compares the requested access and sharing modes to those specified when the file was opened. If you specify an access or sharing mode that conflicts with the modes specified in the previous call, CreateFile fails.
The following table illustrates the valid combinations of two calls to CreateFile using various access modes and sharing modes (dwDesiredAccess, dwShareMode respectively). It does not matter in which order the CreateFile calls are made. However, any subsequent file I/O operations on each file handle will still be constrained by the current access and sharing modes associated with that particular file handle.
| First call to CreateFile | Valid second calls to CreateFile |
|---|---|
| GENERIC_READ, FILE_SHARE_READ |
|
| GENERIC_READ, FILE_SHARE_WRITE |
|
| GENERIC_READ, FILE_SHARE_READ | FILE_SHARE_WRITE
|
| GENERIC_WRITE, FILE_SHARE_READ |
|
| GENERIC_WRITE, FILE_SHARE_WRITE |
|
| GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE
|
| GENERIC_READ, GENERIC_WRITE, FILE_SHARE_READ |
|
| GENERIC_READ, GENERIC_WRITE, FILE_SHARE_WRITE |
|
| GENERIC_READ, GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE |
|
In addition to the standard file attributes, you can also specify security attributes by including a pointer to a SECURITY_ATTRIBUTES structure as the fourth parameter of CreateFile. However, the underlying file system must support security for this to have any effect (for example, the NTFS file system supports it but the various FAT file systems do not). For more information about security attributes, see Access Control.
An application creating a new file can supply an optional handle to a template file, from which CreateFile takes file attributes and extended attributes for creation of the new file.
CreateFile Scenarios
There are several fundamental scenarios for initiating access to a file using the CreateFile function. These are summarized as:
- Creating a new file when a file with that name does not already exist.
- Creating a new file even if a file of the same name already exists, clearing its data and starting empty.
- Opening an existing file only if it exists, and only intact.
- Opening an existing file only if it exists, truncating it to be empty.
- Opening a file always: as-is if it exists, creating a new one if it does not exist.
These scenarios are controlled by the proper use of the dwCreationDisposition parameter. Below is a breakdown of how these scenarios map to values for this parameter and what happens when they are used.
When creating or opening a new file when a file with that name does not already exist (dwCreationDisposition set to either CREATE_NEW, CREATE_ALWAYS, or OPEN_ALWAYS), the CreateFile function performs the following actions:
- Combines the file attributes and flags specified by dwFlagsAndAttributes with FILE_ATTRIBUTE_ARCHIVE.
- Sets the file length to zero.
- Copies the extended attributes supplied by the template file to the new file if the hTemplateFile parameter is specified (this overrides all FILE_ATTRIBUTE_* flags specified earlier).
- Sets the inherit flag specified by the bInheritHandle member and the security descriptor specified by the lpSecurityDescriptor member of the lpSecurityAttributes parameter (SECURITY_ATTRIBUTES structure), if supplied.
When creating a new file even if a file of the same name already exists (dwCreationDisposition set to CREATE_ALWAYS), the CreateFile function performs the following actions:
- Checks current file attributes and security settings for write access, failing if denied.
- Combines the file attributes and flags specified by dwFlagsAndAttributes with FILE_ATTRIBUTE_ARCHIVE and the existing file attributes.
- Sets the file length to zero (that is, any data that was in the file is no longer available and the file is empty).
- Copies the extended attributes supplied by the template file to the new file if the hTemplateFile parameter is specified (this overrides all FILE_ATTRIBUTE_* flags specified earlier).
- Sets the inherit flag specified by the bInheritHandle member of the lpSecurityAttributes parameter (SECURITY_ATTRIBUTES structure) if supplied, but ignores the lpSecurityDescriptor member of the SECURITY_ATTRIBUTES structure.
- If otherwise successful (that is, CreateFile returns a valid handle), calling GetLastError will yield the code ERROR_ALREADY_EXISTS, even though for this particular use-case it is not actually an error as such (if you intended to create a "new" (empty) file in place of the existing one).
When opening an existing file (dwCreationDisposition set to either OPEN_EXISTING, OPEN_ALWAYS, or TRUNCATE_EXISTING), the CreateFile function performs the following actions:
- Checks current file attributes and security settings for requested access, failing if denied.
- Combines the file flags (FILE_FLAG_*) specified by dwFlagsAndAttributes with existing file attributes, and ignores any file attributes (FILE_ATTRIBUTE_*) specified by dwFlagsAndAttributes.
- Sets the file length to zero only if dwCreationDisposition is set to TRUNCATE_EXISTING, otherwise the current file length is maintained and the file is opened as-is.
- Ignores the hTemplateFile parameter.
- Sets the inherit flag specified by the bInheritHandle member of the lpSecurityAttributes parameter (SECURITY_ATTRIBUTES structure) if supplied, but ignores the lpSecurityDescriptor member of the SECURITY_ATTRIBUTES structure.
File Attributes and Directories
File attributes are part of the metadata associated with a file or directory, each with its own purpose and rules on how it can be set and changed. Some of these attributes apply only to files, and some only to directories. For example, the FILE_ATTRIBUTE_DIRECTORY attribute applies only to directories: It is used by the file system to determine whether an object on disk is a directory, but it cannot be changed for an existing file system object.
Some file attributes can be set for a directory but have meaning only for files created in that directory, acting as default attributes. For example, FILE_ATTRIBUTE_COMPRESSED can be set on a directory object, but because the directory object itself contains no actual data, it is not truly compressed; however, directories marked with this attribute tell the file system to compress any new files added to that directory. Any file attribute that can be set on a directory and will also be set for new files added to that directory is referred to as an inherited attribute.
The CreateFile function provides a parameter for setting certain file attributes when a file is created. In general, these attributes are the most common for an application to use at file creation time, but not all possible file attributes are available to CreateFile. Some file attributes require the use of other functions, such as SetFileAttributes, DeviceIoControl, or DecryptFile after the file already exists. In the case of FILE_ATTRIBUTE_DIRECTORY, the CreateDirectory function is required at creation time because CreateFile cannot create directories. The other file attributes that require special handling are FILE_ATTRIBUTE_REPARSE_POINT and FILE_ATTRIBUTE_SPARSE_FILE, which require DeviceIoControl. For more information, see SetFileAttributes.
As stated previously, file attribute inheritance occurs when a file is created with file attributes read from the directory attributes where the file will be located. The following table summarizes these inherited attributes and how they relate to CreateFile capabilities.
| Directory attribute state | CreateFile inheritance override capability for new files |
|---|---|
| FILE_ATTRIBUTE_COMPRESSED set. |
No control. Use DeviceIoControl to clear. |
| FILE_ATTRIBUTE_COMPRESSED not set. |
No control. Use DeviceIoControl to set. |
| FILE_ATTRIBUTE_ENCRYPTED set. |
No control. Use DecryptFile. |
| FILE_ATTRIBUTE_ENCRYPTED not set. |
Can be set using CreateFile. |
| FILE_ATTRIBUTE_NOT_CONTENT_INDEXED set. |
No control. Use SetFileAttributes to clear. |
| FILE_ATTRIBUTE_NOT_CONTENT_INDEXED not set. |
No control. Use SetFileAttributes to set. |