OpenFile function (winbase.h)
Creates, opens, reopens, or deletes a file.
Syntax
Parameters
The name of the file.
The string must consist of characters from the 8-bit Windows character set. The OpenFile function does not support Unicode file names or opening named pipes.
A pointer to the OFSTRUCT structure that receives information about a file when it is first opened.
The structure can be used in subsequent calls to the OpenFile function to see an open file.
The OFSTRUCT structure contains a path string member with a length that is limited to OFS_MAXPATHNAME characters, which is 128 characters. Because of this, you cannot use the OpenFile function to open a file with a path length that exceeds 128 characters. The CreateFile function does not have this path length limitation.
The action to be taken.
This parameter can be one or more of the following values.
| Value | Meaning |
|---|---|
| OF_CANCEL 0x00000800 | Ignored. To produce a dialog box containing a Cancel button, use OF_PROMPT. |
| OF_CREATE 0x00001000 | Creates a new file. If the file exists, it is truncated to zero (0) length. |
| OF_DELETE 0x00000200 | Deletes a file. |
| OF_EXIST 0x00004000 | Opens a file and then closes it. Use this to test for the existence of a file. |
| OF_PARSE 0x00000100 | Fills the OFSTRUCT structure, but does not do anything else. |
| OF_PROMPT 0x00002000 | Displays a dialog box if a requested file does not exist. A dialog box informs a user that the system cannot find a file, and it contains Retry and Cancel buttons. The Cancel button directs OpenFile to return a file-not-found error message. |
| OF_READ 0x00000000 | Opens a file for reading only. |
| OF_READWRITE 0x00000002 | Opens a file with read/write permissions. |
| OF_REOPEN 0x00008000 | Opens a file by using information in the reopen buffer. |
| OF_SHARE_COMPAT 0x00000000 | For MS-DOS–based file systems, opens a file with compatibility mode, allows any process on a specified computer to open the file any number of times. Other efforts to open a file with other sharing modes fail. This flag is mapped to the FILE_SHARE_READ|FILE_SHARE_WRITE flags of the CreateFile function. |
| OF_SHARE_DENY_NONE 0x00000040 | Opens a file without denying read or write access to other processes. On MS-DOS-based file systems, if the file has been opened in compatibility mode by any other process, the function fails. This flag is mapped to the FILE_SHARE_READ|FILE_SHARE_WRITE flags of the CreateFile function. |
| OF_SHARE_DENY_READ 0x00000030 | Opens a file and denies read access to other processes. On MS-DOS-based file systems, if the file has been opened in compatibility mode, or for read access by any other process, the function fails. This flag is mapped to the FILE_SHARE_WRITE flag of the CreateFile function. |
| OF_SHARE_DENY_WRITE 0x00000020 | Opens a file and denies write access to other processes. On MS-DOS-based file systems, if a file has been opened in compatibility mode, or for write access by any other process, the function fails. This flag is mapped to the FILE_SHARE_READ flag of the CreateFile function. |
| OF_SHARE_EXCLUSIVE 0x00000010 | Opens a file with exclusive mode, and denies both read/write access to other processes. If a file has been opened in any other mode for read/write access, even by the current process, the function fails. |
| OF_VERIFY | Verifies that the date and time of a file are the same as when it was opened previously. This is useful as an extra check for read-only files. |
| OF_WRITE 0x00000001 | Opens a file for write access only. |
Return value
If the function succeeds, the return value specifies a file handle to use when performing file I/O. To close the file, call the CloseHandle function using this handle.
If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.
Remarks
If the lpFileName parameter specifies a file name and extension only, this function searches for a matching file in the following directories and the order shown:
- The directory where an application is loaded.
- The current directory.
- The Windows system directory.
Use the GetSystemDirectory function to get the path of this directory.
The 16-bit Windows system directory.
There is not a function that retrieves the path of this directory, but it is searched.
The Windows directory.
Use the GetWindowsDirectory function to get the path of this directory.
The lpFileName parameter cannot contain wildcard characters.
The OpenFile function does not support the OF_SEARCH flag that the 16-bit Windows OpenFile function supports. The OF_SEARCH flag directs the system to search for a matching file even when a file name includes a full path. Use the SearchPath function to search for a file.
A sharing violation occurs if an attempt is made to open a file or directory for deletion on a remote machine when the value of the uStyle parameter is the OF_DELETE access flag OR’ed with any other access flag, and the remote file or directory has not been opened with FILE_SHARE_DELETE share access. To avoid the sharing violation in this scenario, open the remote file or directory with OF_DELETE access only, or call DeleteFile without first opening the file or directory for deletion.
In WindowsВ 8 and Windows ServerВ 2012, this function is supported by the following technologies.
| Technology | Supported |
|---|---|
| Server Message Block (SMB) 3.0 protocol | Yes |
| SMB 3.0 Transparent Failover (TFO) | Yes |
| SMB 3.0 with Scale-out File Shares (SO) | Yes |
| Cluster Shared Volume File System (CsvFS) | Yes |
| Resilient File System (ReFS) | Yes |
В
CsvFs will do redirected IO for compressed files.
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.
