CreateFile

CreateFile

Switch on low bandwidth view

Collapse All

Language Filter

CreateFile

8/28/2008

This function creates, opens, or truncates a file, COM port, device, service, or console. It returns a handle to access the object.

A RAPI version of this function exists called CeCreateFile (RAPI).

Syntax


HANDLE CreateFile(
  LPCTSTR lpFileName,
  DWORD dwDesiredAccess,
  DWORD dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD dwCreationDisposition,
  DWORD dwFlagsAndAttributes,
  HANDLE hTemplateFile
);

Parameters

lpFileName

[in] Pointer to a null-terminated string that specifies the name of the object, such as file, COM port, disk device, or console, to create or open.

If *lpFileName is a path, the default string size limit is MAX_PATH characters. This limit is related to how this function parses paths.

When lpFileName points to a COM port to open, include a colon after the name. When using IrCOMM, specify COM3:.

dwDesiredAccess

[in] Type of access to the object. An application can obtain read-only access, write-only access, read/write access, or device-query access. The following table shows possible values.

Value	Description
GENERIC_EXECUTE	Specifies execute access only.
GENERIC_READ	Specifies read access to the object. Data can be read from the file, and the file pointer can be moved. Combine with GENERIC_WRITE for read/write access.
GENERIC_WRITE	Specifies write access to the object. Data can be written to the file, and the file pointer can be moved. Combine with GENERIC_READ for read/write access.

dwShareMode

[in] Share mode for the object. If this parameter is set to zero, the object cannot be shared. Subsequent open operations on the object fail until the handle is closed.

This parameter can be set to one or more values. The following table shows possible values.

Value	Description
FILE_SHARE_READ	Indicates that subsequent open operations on the object succeed only if read access is requested.
FILE_SHARE_WRITE	Indicates that subsequent open operations on the object succeed only if write access is requested.

lpSecurityAttributes: [in] Not used.

dwCreationDisposition

[in] Action to take on files that exist, and which action to take when files do not exist. The following table shows possible values.

Value	Description
CREATE_ALWAYS	Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes.
OPEN_EXISTING	Opens the file. The function fails if the file does not exist.
CREATE_NEW	Creates a new file. The function fails if the specified file already exists.
OPEN_ALWAYS	Opens the file, if it exists. If the file does not exist, the function creates the file as if this parameter were set to CREATE_NEW.
TRUNCATE_EXISTING	Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.

dwFlagsAndAttributes

[in] File attributes and flags for the file.

Any combination of permitted attributes is acceptable for this parameter. All other file attributes override the FILE_ATTRIBUTE_NORMAL value. The following table shows possible attribute values.

Value	Description
FILE_ATTRIBUTE_ARCHIVE	Indicates that the file is archived. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED	Indicates that the file or directory is compressed. For a file, this means that all data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_HIDDEN	Indicates that the file is hidden. It is not to be included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL	Indicates that the file has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_READONLY	Indicates that the file is read-only.
FILE_ATTRIBUTE_ROMMODULE	Indicates that the file is a DLL module that has an implicit reference from at least one other file that is in the modules section of the image. A file with this attribute set cannot replace the functionality of the DLL with a RAM copy of the same DLL.
FILE_ATTRIBUTE_SYSTEM	Indicates that the file is part of or is used exclusively by the OS.
FILE_ATTRIBUTE_TEMPORARY	Not supported.

The following table shows possible flag values.

Value	Description
FILE_FLAG_NO_BUFFERING	Indicates that the file is opened with no system caching. This does not affect disk caching.
FILE_FLAG_OVERLAPPED	This flag is not supported. However, multiple read/write operations pending on a device at a time are supported.
FILE_FLAG_RANDOM_ACCESS	Indicates that the file is accessed randomly. The system can use this as a hint to optimize file caching.
FILE_FLAG_WRITE_THROUGH	Instructs the system to write through any intermediate cache and go directly to disk. The system can still cache write operations, but cannot lazily flush them.

hTemplateFile: [in] Ignored; as a result, this function does not copy the extended attributes to the new file.

Return Value

An open handle to the specified file indicates success. If the specified file exists before the function call and dwCreationDisposition is set to CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file does not exist before the call, GetLastError returns zero. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

For Windows Embedded CE:

For Windows CE 2.0 1 and earlier, an application cannot use GetLastError to determine whether a file existed before the call to this function.

Remarks

For Windows Embedded CE:

Use the CloseHandle function to close an object handle returned by this function.

This function cannot be used to access files in the MODULES section of ROM. Modules are stored in a different format that applications cannot access. The only ROM files that can be accessed using this function are those in the FILES section.

If the FILE_FLAG_NO_BUFFERING flag is set, the system opens a file with no system caching. This flag does not affect hard disk caching. When combined with FILE_FLAG_OVERLAPPED, the flag gives maximum asynchronous performance because the I/O does not rely on the synchronous operations of the memory manager. However, some I/O operations take more time because data is not being held in the cache. In addition, the file metadata may still be cached. To flush the metadata to disk, use the FlushFileBuffers function.

An application must meet certain requirements when working with files that are opened with FILE_FLAG_NO_BUFFERING:

File access must begin at byte offsets within a file that are integer multiples of the volume sector size.

File access must be for numbers of bytes that are integer multiples of the volume sector size. For example, if the sector size is 512 bytes, an application can request reads and writes of 512, 1024, 1536, or 2048 bytes, but not of 335, 981, or 7171 bytes.

Buffer addresses for read and write operations may have to be sector aligned, which means aligned on addresses in memory that are integer multiples of the volume sector size. Depending on the disk, this requirement may not be enforced.

One way to align buffers on integer multiples of the volume sector size is to use the VirtualAlloc function to allocate buffers. VirtualAlloc allocates memory that is aligned on addresses that are integer multiples of OS memory page size. Because both memory page and volume sector sizes are powers of 2, this memory is also aligned on addresses that are integer multiples of a volume sector size. Memory pages are 4 to 8 KB in size. Sectors are 512 bytes (hard disks) or 2048 bytes (CD). Therefore, volume sectors can never be larger than memory pages.

An application can check the volume sector size by calling the GetDiskFreeSpaceEx function.

For Windows Embedded CE:

For more information, see CreateFile Overview.

Requirements

Header	winbase.h
Library	coredll.lib
Windows Embedded CE	Windows CE 1.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

Reference

File I/O Functions
CloseHandle
CreateDirectory
ReadFile

Other Resources

Services.exe