Share via

CreateFile (Compact 2013)

  • Article

3/26/2014

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

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 of the values shown in the following table*.*

    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_BACKUP_SEMANTICS

    Indicates that the CreateFile operation is to get a handle to the file directory.

    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.
  • 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.

Remarks

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 disk) or 2048 bytes (CD). Therefore, volume sectors can never be larger than memory pages.

The HKEY_LOCAL_MACHINE\System\StorageManager\FATFS\DirHandleWrite registry value must be set to 1 in order to get a writable handle to the file directory when using the FILE_FLAG_BACKUP_SEMANTICS flag. This registry setting is not required to get a read-only handle to the file directory. For more information about editing the registry, see Registry Settings for FATFS Disk Caching.

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

Requirements

Header

winbase.h

Library

coredll.lib

See Also

Reference

File I/O Functions
CloseHandle
CreateDirectory
ReadFile

Other Resources

Servicesd.exe