The Windows Disk Management 7

 

 

 

 

 

CreateFile() Function

 

Creates or opens a file or I/O device. The most commonly used I/O devices are as follows: file, file stream, directory, physical disk, volume, console buffer, tape drive, communications resource, mailslot, and pipe. The function returns a handle that can be used to access the file or device for various types of I/O depending on the file or device and the flags and attributes specified. To perform this operation as a transacted operation, which results in a handle that can be used for transacted I/O, use the CreateFileTransacted() function. The syntax is:

 

HANDLE WINAPI CreateFile(

       LPCTSTR lpFileName,

       DWORD dwDesiredAccess,

       DWORD dwShareMode,

       LPSECURITY_ATTRIBUTES lpSecurityAttributes,

       DWORD dwCreationDisposition,

       DWORD dwFlagsAndAttributes,

       HANDLE hTemplateFile

);

 

Parameters

 

lpFileName [in] - The name of the file or device to be created or opened. In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. To create a file stream, specify the name of the file, a colon, and then the name of the stream.

dwDesiredAccess [in] - The requested access to the file or device, which can be summarized as read, write, both or neither (zero). The most commonly used values are GENERIC_READ, GENERIC_WRITE, or both (GENERIC_READ | GENERIC_WRITE).

If this parameter is zero, the application can query certain metadata such as file, directory, or device attributes without accessing that file or device, even if GENERIC_READ access would have been denied. You cannot request an access mode that conflicts with the sharing mode that is specified by the dwShareMode parameter in an open request that already has an open handle.

dwShareMode [in] - The requested sharing mode of the file or device, which can be read, write, both, delete, all of these, or none (refer to the following table). Access requests to attributes or extended attributes are not affected by this flag.

If this parameter is zero and CreateFile() succeeds, the file or device cannot be shared and cannot be opened again until the handle to the file or device is closed.

You cannot request a sharing mode that conflicts with the access mode that is specified in an existing request that has an open handle. CreateFile() would fail and the GetLastError() function would return ERROR_SHARING_VIOLATION. To enable a process to share a file or device while another process has the file or device open, use a compatible combination of one or more of the following values. The sharing options for each open handle remain in effect until that handle is closed, regardless of process context.

 

String Constant (Value)

Meaning

0 (0x00000000)

Prevents other processes from opening a file or device if they request delete, read, or write access.

FILE_SHARE_DELETE

(0x00000004)

Enables subsequent open operations on a file or device to request delete access. Otherwise, other processes cannot open the file or device if they request delete access. If this flag is not specified, but the file or device has been opened for delete access, the function fails. The delete access allows both delete and rename operations.

FILE_SHARE_READ

(0x00000001)

Enables subsequent open operations on a file or device to request read access. Otherwise, other processes cannot open the file or device if they request read access. If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILE_SHARE_WRITE

(0x00000002)

Enables subsequent open operations on a file or device to request write access. Otherwise, other processes cannot open the file or device if they request write access. If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.

 

lpSecurityAttributes [in, optional] - A pointer to a SECURITY_ATTRIBUTES structure that contains two separate but related data members: an optional security descriptor, and a Boolean value that determines whether the returned handle can be inherited by child processes. This parameter can be NULL. If this parameter is NULL, the handle returned by CreateFile() cannot be inherited by any child processes the application may create and the file or device associated with the returned handle gets a default security descriptor.

The lpSecurityDescriptor member of the structure specifies a SECURITY_DESCRIPTOR for a file or device. If this member is NULL, the file or device associated with the returned handle is assigned a default security descriptor.

CreateFile() ignores the lpSecurityDescriptor member when opening an existing file or device, but continues to use the bInheritHandle member. The bInheritHandle member of the structure specifies whether the returned handle can be inherited.

dwCreationDisposition [in] - An action to take on a file or device that exists or does not exist. For devices other than files, this parameter is usually set to OPEN_EXISTING. This parameter must be one of the following values, which cannot be combined:

 

String Constant (Value)

Meaning

CREATE_ALWAYS (2)

Creates a new file, always.

If the specified file exists and is writable, the function overwrites the file, the function succeeds, and last-error code is set to ERROR_ALREADY_EXISTS (183). If the specified file does not exist and is a valid path, a new file is created, the function succeeds, and the last-error code is set to zero.

CREATE_NEW (1)

Creates a new file, only if it does not already exist.

If the specified file exists, the function fails and the last-error code is set to ERROR_FILE_EXISTS (80). If the specified file does not exist and is a valid path to a writable location, a new file is created.

OPEN_ALWAYS (4)

Opens a file, always.

If the specified file exists, the function succeeds and the last-error code is set to ERROR_ALREADY_EXISTS (183). If the specified file does not exist and is a valid path to a writable location, the function creates a file and the last-error code is set to zero.

OPEN_EXISTING (3)

Opens a file or device, only if it exists.

If the specified file or device does not exist, the function fails and the last-error code is set to ERROR_FILE_NOT_FOUND (2).

TRUNCATE_EXISTING (5)

Opens a file and truncates it so that its size is zero bytes, only if it exists.

If the specified file does not exist, the function fails and the last-error code is set to ERROR_FILE_NOT_FOUND (2). The calling process must open the file with the GENERIC_WRITE bit set as part of the dwDesiredAccess parameter.

 

dwFlagsAndAttributes [in] - The file or device attributes and flags, FILE_ATTRIBUTE_NORMAL being the most common default value for files. This parameter can include any combination of the available file attributes (FILE_ATTRIBUTE_*). All other file attributes override FILE_ATTRIBUTE_NORMAL. This parameter can also contain combinations of flags (FILE_FLAG_*) for control of file or device caching behavior, access modes, and other special-purpose flags. These combine with any FILE_ATTRIBUTE_* values.

This parameter can also contain Security Quality of Service information by specifying the SECURITY_SQOS_PRESENT flag. Additional SQOS-related flags information is presented in the table following the attributes and flags tables.

When CreateFile() opens an existing file, it generally combines the file flags with the file attributes of the existing file, and ignores any file attributes supplied as part of dwFlagsAndAttributes. Some of the following file attributes and flags may only apply to files and not necessarily all other types of devices that CreateFile() can open.

 

String Constant (Dec (Hex) value)) Attribute

Meaning

FILE_ATTRIBUTE_ARCHIVE (32 (0x20))

The file should be archived. Applications use this attribute to mark files for backup or removal.

FILE_ATTRIBUTE_ENCRYPTED (16384 (0x4000))

The file or directory is encrypted. For a file, this means that all data in the file is encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories. This flag has no effect if FILE_ATTRIBUTE_SYSTEM is also specified.

FILE_ATTRIBUTE_HIDDEN (2 (0x2))

The file is hidden. Do not include it in an ordinary directory listing.

FILE_ATTRIBUTE_NORMAL (128 (0x80))

The file does not have other attributes set. This attribute is valid only if used alone.

FILE_ATTRIBUTE_OFFLINE (4096 (0x1000))

The data of a file is not immediately available. This attribute indicates that file data is physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software. Applications should not arbitrarily change this attribute.

FILE_ATTRIBUTE_READONLY (1 (0x1))

The file is read only. Applications can read the file, but cannot write to or delete it.

FILE_ATTRIBUTE_SYSTEM (4 (0x4))

The file is part of or used exclusively by an operating system.

FILE_ATTRIBUTE_TEMPORARY (256 (0x100))

The file is being used for temporary storage.

 

 

 

 

String Constant (Value) Flag

Meaning

FILE_FLAG_BACKUP_SEMANTICS (0x02000000)

The file is being opened or created for a backup or restore operation. The system ensures that the calling process overrides file security checks when the process has SE_BACKUP_NAME and SE_RESTORE_NAME privileges.

You must set this flag to obtain a handle to a directory. A directory handle can be passed to some functions instead of a file handle.

FILE_FLAG_DELETE_ON_CLOSE (0x04000000)

The file is to be deleted immediately after all of its handles are closed, which includes the specified handle and any other open or duplicated handles.

If there are existing open handles to a file, the call fails unless they were all opened with the FILE_SHARE_DELETE share mode.

Subsequent open requests for the file fail, unless the FILE_SHARE_DELETE share mode is specified.

FILE_FLAG_NO_BUFFERING (0x20000000)

The file or device is being opened with no system caching for data reads and writes. This flag does not affect hard disk caching or memory mapped files.

There are strict requirements for successfully working with files opened with CreateFile() using the FILE_FLAG_NO_BUFFERING flag.

FILE_FLAG_OPEN_NO_RECALL (0x00100000)

The file data is requested, but it should continue to be located in remote storage. It should not be transported back to local storage. This flag is for use by remote storage systems.

FILE_FLAG_OPEN_REPARSE_POINT (0x00200000)

Normal reparse point processing will not occur; CreateFile() will attempt to open the reparse point. When a file is opened, a file handle is returned, whether or not the filter that controls the reparse point is operational.

This flag cannot be used with the CREATE_ALWAYS flag. If the file is not a reparse point, then this flag is ignored.

FILE_FLAG_OVERLAPPED (0x40000000)

The file or device is being opened or created for asynchronous I/O. When subsequent I/O operations are completed on this handle, the event specified in the OVERLAPPED structure will be set to the signaled state.

If this flag is specified, the file can be used for simultaneous read and write operations.

If this flag is not specified, then I/O operations are serialized, even if the calls to the read and write functions specify an OVERLAPPED structure.

FILE_FLAG_POSIX_SEMANTICS (0x0100000)

Access will occur according to POSIX rules. This includes allowing multiple files with names, differing only in case, for file systems that support that naming. Use care when using this option, because files created with this flag may not be accessible by applications that are written for MS-DOS or 16-bit Windows.

FILE_FLAG_RANDOM_ACCESS (0x10000000)

Access is intended to be random. The system can use this as a hint to optimize file caching. This flag has no effect if the file system does not support cached I/O and FILE_FLAG_NO_BUFFERING.

FILE_FLAG_SEQUENTIAL_SCAN (0x08000000)

Access is intended to be sequential from beginning to end. The system can use this as a hint to optimize file caching. This flag should not be used if read-behind (that is, backwards scans) will be used.

This flag has no effect if the file system does not support cached I/O and FILE_FLAG_NO_BUFFERING.

FILE_FLAG_WRITE_THROUGH (0x80000000)

Write operations will not go through any intermediate cache, they will go directly to disk.

 

The dwFlagsAndAttributes parameter can also specify Security Quality of Service information. When the calling application specifies the SECURITY_SQOS_PRESENT flag as part of dwFlagsAndAttributes, it can also contain one or more of the following values.

 

Security flag

Meaning

SECURITY_ANONYMOUS

Impersonates a client at the Anonymous impersonation level.

SECURITY_CONTEXT_TRACKING

The security tracking mode is dynamic. If this flag is not specified, the security tracking mode is static.

SECURITY_DELEGATION

Impersonates a client at the Delegation impersonation level.

SECURITY_EFFECTIVE_ONLY

Only the enabled aspects of the client's security context are available to the server. If you do not specify this flag, all aspects of the client's security context are available. This allows the client to limit the groups and privileges that a server can use while impersonating the client.

SECURITY_IDENTIFICATION

Impersonates a client at the Identification impersonation level.

SECURITY_IMPERSONATION

Impersonate a client at the impersonation level. This is the default behavior if no other flags are specified along with the SECURITY_SQOS_PRESENT flag.

 

hTemplateFile [in, optional] - A valid handle to a template file with the GENERIC_READ access right. The template file supplies file attributes and extended attributes for the file that is being created. This parameter can be NULL. When opening an existing file, CreateFile() ignores this parameter. When opening a new encrypted file, the file inherits the discretionary access control list from its parent directory.

 

Return Value

 

If the function succeeds, the return value is an open handle to the specified file, device, named pipe, or mail slot. If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError().

CreateFile() was originally developed specifically for file interaction but has since been expanded and enhanced to include most other types of I/O devices and mechanisms available to Windows developers. This section attempts to cover the varied issues developers may experience when using CreateFile() in different contexts and with different I/O types. The text attempts to use the word file only when referring specifically to data stored in an actual file on a file system. However, some uses of file may be referring more generally to an I/O object that supports file-like mechanisms. This liberal use of the term file is particularly prevalent in constant names and parameter names because of the previously mentioned historical reasons.

When an application is finished using the object handle returned by CreateFile(), use the CloseHandle() function to close the handle. This not only frees up system resources, but can have wider influence on things like sharing the file or device and committing data to disk. Specifics are noted within this topic as appropriate. For Windows Server 2003 and Windows XP/2000:  A sharing violation occurs if an attempt is made to open a file or directory for deletion on a remote computer when the value of the dwDesiredAccess parameter is the DELETE access flag OR'ed with any other access flag, and the remote file or directory has not been opened with FILE_SHARE_DELETE. To avoid the sharing violation in this scenario, open the remote file or directory with the DELETE access right only, or call DeleteFile() without first opening the file or directory for deletion. Some file systems, such as the NTFS file system, support compression or encryption for individual files and directories. On volumes that have a mounted file system with this support, a new file inherits the compression and encryption attributes of its directory. You cannot use CreateFile() to control compression, decompression, or decryption on a file or directory.

For Windows Server 2003 and Windows XP/2000:  For backward compatibility purposes, CreateFile() does not apply inheritance rules when you specify a security descriptor in lpSecurityAttributes. To support inheritance, functions that later query the security descriptor of this file may heuristically determine and report that inheritance is in effect. As stated previously, if the lpSecurityAttributes parameter is NULL, the handle returned by CreateFile() cannot be inherited by any child processes your application may create. The following information regarding this parameter also applies:

 

  1. If the bInheritHandle member variable is not FALSE, which is any non-zero value, then the handle can be inherited. Therefore it is critical this structure member be properly initialized to FALSE if you do not intend the handle to be inheritable.
  2. The access control lists (ACL) in the default security descriptor for a file or directory are inherited from its parent directory.
  3. The target file system must support security on files and directories for the lpSecurityDescriptor member to have an effect on them, which can be determined by using GetVolumeInformation().

 

 

 

 

< Windows Disk 6 | Win32 Programming Index Page | Windows Disk Index | Windows Disk 8 >