CreateFile Overview

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

Use the CreateFile function to open or create files, and to get a handle to use with a COM port, storage volume, disk drive, drive partition, service, or console.

Using CreateFile with Files

CreateFile 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 OS adds it to the specified directory.

When an application uses CreateFile, it must use the dwDesiredAccess parameter to specify the access mode: whether it reads from the file, writes to the file, or both. The application must also specify what action to take if the file already exists. For example, an application can call CreateFile with CREATE_ALWAYS to create the file if it does not already exist, and overwrite the file if it does exist.

In addition to the characteristics described in the dwDesiredAccess parameter, CreateFile includes a pointer to a SECURITY_ATTRIBUTES structure, if it exists. The provided SECURITY_ATTRIBUTES structure is applied only if the file does not already exist at the time of creation. Even if dwCreationDisposition is set to CREATE_ALWAYS, which clears attributes and size, the existing security descriptor remains the same if the file already exists. An application cannot create a file with a security descriptor that disallows the requested access mode.

When a process attempts to open a file that has already been opened in sharing mode, the system compares the requested access and sharing modes to those specified when the file was opened. If you specify an access mode that conflicts with the sharing mode specified in the previous open call, CreateFile fails with a sharing violation, ERROR_SHARING_VIOLATION. If you specify a sharing mode that conflicts with the access mode specified in the previous open call, CreateFile fails with a sharing violation.

When creating a new file, CreateFile performs the following actions:

• Clears the existing file attributes (CREATE_ALWAYS with an existing file only).
• Combines the file attributes and flags specified by dwFlagsAndAttributes with FILE_ATTRIBUTE_ARCHIVE.
• Sets the file length to zero.

When opening an existing file, CreateFile performs the following actions:

• Combines the file flags (FILE_FLAG_*) specified by dwFlagsAndAttributes with existing file attributes. CreateFile ignores the file attributes (FILE_ATTRIBUTE_*) specified by dwFlagsAndAttributes.
• Sets the file length according to the value of dwCreationDisposition.
• Ignores the lpSecurityDescriptor member of the SECURITY_ATTRIBUTES structure. The other structure members are used, for example, bInheritHandle indicates whether the file handle can be inherited.

The OS assigns a unique identifier, called a file handle, to each file that is opened or created. An application can use the file handle in functions that read from, write to, and describe the file. It is valid until the file is closed. When an application starts, it inherits all open file handles from the process that started it, if the handles are inheritable.

An application should check the return value of CreateFile before attempting to use the handle to access the file. If an error occurs, the application can use the GetLastError function to get extended error information.

The following practices will help make optimal use of CreateFile:

• File naming for maximum storage
  To store the maximum number of files on PC card storage devices, limit file names to eight uppercase characters and file extensions to three uppercase characters. Do not use non-OEM characters in file names. File names that do not conform to these limits require more than one physical directory entry on a PC card.
• Compression
  To prevent a file from being compressed, use the FILE_FLAG_RANDOM_ACCESS flag in the RAM file system. This places files in the object store and prevents a file from being compressed. If performance is an issue, this could be the correct solution. Read and write operations to a compressed file are slower than read and write operations to an uncompressed file.
• Caching
  Volume handles can be opened as non-cached at the discretion of the file system, even when the non-cached option is not specified with CreateFile. You can assume that all Microsoft file systems open volume handles as non-cached. The restrictions on non-cached I/O for files also apply to volumes.
  A file system may require buffer alignment, even though the data is non-cached. However, if the non-cached option is specified when opening a volume, buffer alignment is enforced, regardless of the file system on the volume. All file systems should open volume handles as non-cached and follow the non-cached I/O restrictions.
  CreateFile should only be used on a privileged $bus handle. For more information, see Device Manager Security.
• Accessing directories other than \Windows
  To access a file in a directory other than \Windows or the root directory, supply the absolute path to the file. The OS does not support a current directory. If a path to a file is not supplied along with the file name, the OS looks for the file in the \Windows directory, as well as in the root of the file system. In some cases, the GetModuleFileName function can supply the working directory of the currently running executable file.

Using CreateFile with Other Elements

You can use CreateFile to get a handle to use with a COM port, disk drive, drive partition, or console.

• COM ports
  CreateFile can create a handle to a COM port. By setting the dwCreationDisposition parameter to OPEN_EXISTING, read-only, write-only, or read/write access can be specified.
• Disk drive or drive partition
  You can use CreateFile to open a disk drive or a partition on a disk drive. The function returns a handle to the disk device. That handle can be used with the DeviceIoControl function.
  The following list shows the requirements that must be met for such a call to succeed:
  • The caller must have administrative privileges for the operation to succeed on a hard disk drive.
  • The lpFileName string should be of the form DSKx: to open the hard disk x. Hard disk numbers start at 1. For example, DSK2: obtains a handle to the second physical drive on the computer.
  • The dwCreationDisposition parameter must be set to OPEN_EXISTING.
  • When opening a disk or a partition on a hard disk, set the FILE_SHARE_WRITE flag in the dwShareMode parameter.
• Consoles
  If Console.dll is present in the OS image, an application can use the direct console name, CONn:, to open the console with CreateFile, if it has been previously registered. The n is a number between zero and 9.

See Also

Concepts

Creating, Deleting, and Maintaining Files
Creating and Opening a File or Directory