以下程式碼包含了GetSystemDirectory, CreateFile, WriteFile, CloseHandle四支Windows API
另,部份相關知識可參考MSDN：http://msdn.microsoft.com/zh-tw/library/w4byd5y4(VS.80).aspx
也可查閱PINVOKE.NET網站：http://www.pinvoke.net/index.aspx
Imports System.Runtime.InteropServices
Public Class Form1
'Private Declare Function GetSystemDirectory Lib "kernel32" Alias "GetSystemDirectoryA" (ByVal lpBuffer As Byte(), ByVal uSize As Integer) As Integer
'底下用法必須引用System.Runtime.InteropServices
_
Private Shared Function GetSystemDirectory(ByVal lpBuffer As Byte(), ByVal uSize As Integer) As Integer
End Function
'Private Declare Function CreateFile Lib "kernel32" Alias "CreateFileA" (ByVal lpFileName As String, ByVal dwDesiredAccess As EFileAccess, ByVal dwShareMode As EFileShare, ByVal lpSecurityAttributes As IntPtr, ByVal dwCreationDisposition As ECreationDisposition, ByVal dwFlagsAndAttributes As EFileAttributes, ByVal hTemplateFile As IntPtr) As IntPtr
_
Private Shared Function CreateFile(ByVal lpFileName As String, ByVal dwDesiredAccess As EFileAccess, ByVal dwShareMode As EFileShare, ByVal lpSecurityAttributes As IntPtr, ByVal dwCreationDisposition As ECreationDisposition, ByVal dwFlagsAndAttributes As EFileAttributes, ByVal hTemplateFile As IntPtr) As IntPtr
End Function
'Private Declare Function WriteFile Lib "kernel32" Alias "WriteFile" (ByVal hFile As IntPtr, ByVal lpBuffer As String, ByVal nNumberOfBytesWritten As Integer, ByVal lpNumberOfBytesWritten As Integer, ByRef lpOverlapped As OVERLAPPED) As Boolean
_
Public Shared Function WriteFile(ByVal hFile As IntPtr, ByVal lpBuffer As String, ByVal nNumberOfBytesWritten As Integer, ByVal lpNumberOfBytesWritten As Integer, ByRef lpOverlapped As OVERLAPPED) As Boolean
End Function
'Public Declare Function CloseHandle Lib "kernel32" Alias "CloseHandle" (ByVal hObject As IntPtr) As Boolean
_
Public Shared Function CloseHandle(ByVal hObject As IntPtr) As Boolean
End Function
Private Structure LPSECURITY_ATTRIBUTE
Dim nLength As Integer
Dim lpSecurityDescription As Integer
Dim hInheritHandle As Integer
End Structure
Structure OVERLAPPED
Dim Internal As Integer
Dim InternalHigh As Integer
Dim offset As Integer
Dim OffsetHigh As Integer
Dim hEvent As Integer
End Structure
Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
Dim nMAX_PATH As Integer = 260
'Dim sSystemDir As String = Strings.StrDup(nMAX_PATH, " ")
Dim bSystemDir As Byte()
ReDim bSystemDir(nMAX_PATH)
'獲取系統目錄
Dim nStrLen As Integer = GetSystemDirectory(bSystemDir, nMAX_PATH)
'sSystemDir = Strings.Left(sSystemDir, nStrLen) '去除實際字串尾端由chr(0)起所截斷的部份
Dim sSystemDir As String = System.Text.Encoding.Default.GetString(bSystemDir)
sSystemDir = Strings.Left(sSystemDir, nStrLen) '去除實際字串尾端由chr(0)起所截斷的部份
'底下用到EFileAccess, EFileShare, ECreationDisposition, EFileAttributes 四組Enum
Dim hFile As Int32 = CreateFile("c:\systemroot.txt", EFileAccess.GENERIC_WRITE, EFileShare.FILE_SHARE_NONE, 0, ECreationDisposition.CREATE_ALWAYS, EFileAttributes.FILE_ATTRIBUTE_NORMAL, vbNull)
If hFile = -1 Then MsgBox("CreateFile錯誤, 可能檔案已存在. CreateFile之CreationDisposition參數若改用CREATE_ALWAYS則永遠都會建立之") : Exit Sub
If Not WriteFile(hFile, sSystemDir, Len(sSystemDir), 0, New OVERLAPPED) Then
MsgBox("Error Number:" & Err.LastDllError)
End If
CloseHandle(hFile)
MsgBox(sSystemDir & "---")
End Sub
End Class
Friend Enum EFileAccess As System.Int32
''
'' The following are masks for the predefined standard access types
''
DELETE = &H10000
READ_CONTROL = &H20000
WRITE_DAC = &H40000
WRITE_OWNER = &H80000
SYNCHRONIZE = &H100000
STANDARD_RIGHTS_REQUIRED = &HF0000
STANDARD_RIGHTS_READ = READ_CONTROL
STANDARD_RIGHTS_WRITE = READ_CONTROL
STANDARD_RIGHTS_EXECUTE = READ_CONTROL
STANDARD_RIGHTS_ALL = &H1F0000
SPECIFIC_RIGHTS_ALL = &HFFFF
''
'' AccessSystemAcl access type
''
ACCESS_SYSTEM_SECURITY = &H1000000
''
'' MaximumAllowed access type
''
MAXIMUM_ALLOWED = &H2000000
''
'' These are the generic rights.
''
GENERIC_READ = &H80000000
GENERIC_WRITE = &H40000000
GENERIC_EXECUTE = &H20000000
GENERIC_ALL = &H10000000
End Enum
Friend Enum EFileShare
FILE_SHARE_NONE = &H0
FILE_SHARE_READ = &H1
FILE_SHARE_WRITE = &H2
FILE_SHARE_DELETE = &H4
End Enum
Friend Enum ECreationDisposition
'''
''' 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.
'''
CREATE_NEW = 1
'''
''' 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.
''' For more information, see the Remarks section of this topic.
'''
CREATE_ALWAYS = 2
'''
''' 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).
''' For more information about devices, see the Remarks section.
'''
OPEN_EXISTING = 3
'''
''' 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_ALWAYS = 4
'''
''' 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.
'''
TRUNCATE_EXISTING = 5
End Enum
Friend Enum EFileAttributes
FILE_ATTRIBUTE_READONLY = &H1
FILE_ATTRIBUTE_HIDDEN = &H2
FILE_ATTRIBUTE_SYSTEM = &H4
FILE_ATTRIBUTE_DIRECTORY = &H10
FILE_ATTRIBUTE_ARCHIVE = &H20
FILE_ATTRIBUTE_DEVICE = &H40
FILE_ATTRIBUTE_NORMAL = &H80
FILE_ATTRIBUTE_TEMPORARY = &H100
FILE_ATTRIBUTE_SPARSE_FILE = &H200
FILE_ATTRIBUTE_REPARSE_POINT = &H400
FILE_ATTRIBUTE_COMPRESSED = &H800
FILE_ATTRIBUTE_OFFLINE = &H1000
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED = &H2000
FILE_ATTRIBUTE_ENCRYPTED = &H4000
FILE_ATTRIBUTE_VIRTUAL = &H10000
'This parameter can also contain combinations of flags (FILE_FLAG_*)
FILE_FLAG_BACKUP_SEMANTICS = &H2000000
FILE_FLAG_DELETE_ON_CLOSE = &H4000000
FILE_FLAG_NO_BUFFERING = &H2000000
FILE_FLAG_OPEN_NO_RECALL = &H100000
FILE_FLAG_OPEN_REPARSE_POINT = &H200000
FILE_FLAG_OVERLAPPED = &H40000000
FILE_FLAG_POSIX_SEMANTICS = &H100000
FILE_FLAG_RANDOM_ACCESS = &H10000000
FILE_FLAG_SEQUENTIAL_SCAN = &H8000000
FILE_FLAG_WRITE_THROUGH = &H80000000
End Enum
ＶＣ＋＋２００８：
#include <windows.h>
int main(int argc, TCHAR argv[])
{
//檔案處理
HANDLE hFile;
DWORD dwWritten;
//字串變數,用於儲存系統目錄
TCHAR szSystemDir[MAX_PATH];
//獲取系統目錄
GetSystemDirectory(szSystemDir, MAX_PATH);
//建立檔案systemroot.txt
hFile=CreateFile("systemroot.txt",
GENERIC_WRITE,
0, NULL, CREATE_ALWAYS,
FILE_ATTRIBUTE_NORMAL,
NULL);
//判斷檔案是否建立成功
if(hFile != INVALID_HANDLE_VALUE)
{
//將系統目錄系統資訊寫入檔案
if(!WriteFile(hFile,szSystemDir,lstrlen(szSystemDir),&dwWritten,NULL))
{
return GetLastError();
}
}
//關閉檔案,回傳
CloseHandle(hFile);
return 0;
}
WinBase.h：
WINBASEAPI
__out
HANDLE
WINAPI
CreateFileA(
__in LPCSTR lpFileName,
__in DWORD dwDesiredAccess,
__in DWORD dwShareMode,
__in_opt LPSECURITY_ATTRIBUTES lpSecurityAttributes,
__in DWORD dwCreationDisposition,
__in DWORD dwFlagsAndAttributes,
__in_opt HANDLE hTemplateFile
);
WINBASEAPI
__out
HANDLE
WINAPI
CreateFileW(
__in LPCWSTR lpFileName,
__in DWORD dwDesiredAccess,
__in DWORD dwShareMode,
__in_opt LPSECURITY_ATTRIBUTES lpSecurityAttributes,
__in DWORD dwCreationDisposition,
__in DWORD dwFlagsAndAttributes,
__in_opt HANDLE hTemplateFile
);
#ifdef UNICODE
#define CreateFile CreateFileW
#else
#define CreateFile CreateFileA
#endif // !UNICODE
WinNT.h：
//
// These are the generic rights.
//
#define GENERIC_READ (0x80000000L)
#define GENERIC_WRITE (0x40000000L)
#define GENERIC_EXECUTE (0x20000000L)
#define GENERIC_ALL (0x10000000L)
ＭＳＤＮ：
CreateFile Function
Creates or opens a file, file stream, directory, physical disk, volume, console buffer, tape drive, communications resource, mailslot, or named pipe. The function returns a handle that can be used to access the object.
To perform this operation as a transacted operation, use the CreateFileTransacted function.
HANDLE WINAPI CreateFile(
__in LPCTSTR lpFileName,
__in DWORD dwDesiredAccess,
__in DWORD dwShareMode,
__in LPSECURITY_ATTRIBUTES lpSecurityAttributes,
__in DWORD dwCreationDisposition,
__in DWORD dwFlagsAndAttributes,
__in HANDLE hTemplateFile
);
Parameters
lpFileName
The name of the object 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. For more information, see Naming a File. For information on special device names, see Defining an MS-DOS Device Name.
To specify a COM port number greater than 9, use the following syntax: "\\.\COM10". This syntax works for all port numbers and hardware that allows COM port numbers to be specified.
To create a file stream, specify the name of the file, a colon, and then the name of the stream. For more information, see File Streams.
dwDesiredAccess
The access to the object, which can be read, write, or both.
For more information, see File Security and Access Rights. You cannot request an access mode that conflicts with the sharing mode that is specified in an open request that has an open handle.
If this parameter is zero (0), the application can query file and device attributes without accessing a device. This is useful for an application to determine the size of a floppy disk drive and the formats it supports without requiring a floppy in a drive. It can also be used to test for the existence of a file or directory without opening them for read or write access.
dwShareMode
The sharing mode of an object, which can be read, write, both, or none.
You cannot request a sharing mode that conflicts with the access mode that is specified in an open request that has an open handle, because that would result in the following sharing violation: ERROR_SHARING_VIOLATION. For more information, see Creating and Opening Files.
If this parameter is zero (0) and CreateFile succeeds, the object cannot be shared and cannot be opened again until the handle is closed. For more information, see the Remarks section of this topic.
The sharing options remain in effect until you close the handle to an object.
To enable a process to share an object while another process has the object open, use a combination of one or more of the following values to specify the access mode they can request to open the object.
Value Meaning
FILE_SHARE_DELETE
Enables subsequent open operations on an object to request delete access.
Otherwise, other processes cannot open the object if they request delete access.
If this flag is not specified, but the object has been opened for delete access, the function fails.
FILE_SHARE_READ
Enables subsequent open operations on an object to request read access.
Otherwise, other processes cannot open the object if they request read access.
If this flag is not specified, but the object has been opened for read access, the function fails.
FILE_SHARE_WRITE
Enables subsequent open operations on an object to request write access.
Otherwise, other processes cannot open the object if they request write access.
If this flag is not specified, but the object has been opened for write access or has a file mapping with write access, the function fails.
lpSecurityAttributes
A pointer to a SECURITY_ATTRIBUTES structure that determines whether or not the returned handle can be inherited by child processes.
If lpSecurityAttributes is NULL, the handle cannot be inherited.
The lpSecurityDescriptor member of the structure specifies a security descriptor for an object. If lpSecurityAttributes is NULL, the object gets a default security descriptor. The access control lists (ACL) in the default security descriptor for a file or directory are inherited from its parent directory.
The target file system must support security on files and directories for this parameter to have an effect on them, which is indicated when GetVolumeInformation returns FS_PERSISTENT_ACLS.
CreateFile ignores lpSecurityDescriptor when opening an existing file, but continues to use the other structure members.
dwCreationDisposition
An action to take on files that exist and do not exist.
For more information, see the Remarks section of this topic.
This parameter must be one of the following values.
Value Meaning
CREATE_ALWAYS
Creates a new file, always.
If a file exists, the function overwrites the file, clears the existing attributes, combines the specified file attributes, and flags with FILE_ATTRIBUTE_ARCHIVE, but does not set the security descriptor that the SECURITY_ATTRIBUTES structure specifies.
CREATE_NEW
Creates a new file.
The function fails if a specified file exists.
OPEN_ALWAYS
Opens a file, always.
If a file does not exist, the function creates a file as if dwCreationDisposition is CREATE_NEW.
OPEN_EXISTING
Opens a file.
The function fails if the file does not exist.
For more information, see the Remarks section of this topic.
TRUNCATE_EXISTING
Opens a file and truncates it so that its size is zero (0) bytes.
The function fails if the file does not exist.
The calling process must open the file with the GENERIC_WRITE access right.
dwFlagsAndAttributes
The file attributes and flags.
This parameter can include any combination of the file attributes. All other file attributes override FILE_ATTRIBUTE_NORMAL.
When CreateFile opens a file, it combines the file flags with existing file attributes, and ignores any supplied file attributes.
The following file attributes and flags are used only for file objects, not other types of objects that CreateFile creates.
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. For more information, see File Encryption.
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. File systems avoid writing data back to mass storage if sufficient cache memory is available, because an application deletes a temporary file after a handle is closed. In that case, the system can entirely avoid writing the data. Otherwise, the data is written after the handle is closed.
This parameter can also include any combination of the following flags.
Value Meaning
FILE_FLAG_BACKUP_SEMANTICS
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. For more information, see Changing Privileges in a Token.
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. For more information, see Directory Handles.
FILE_FLAG_DELETE_ON_CLOSE
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
The file is being opened with no system caching. This flag does not affect hard disk caching or memory mapped files. 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. Also, 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 should 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 VirtualAlloc to allocate the buffers. It allocates memory that is aligned on addresses that are integer multiples of the operating system's 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-8 KB in size; sectors are 512 bytes (hard disks) or 2048 bytes (CD), and therefore, volume sectors can never be larger than memory pages.
An application can determine a volume sector size by calling the GetDiskFreeSpace function.
FILE_FLAG_OPEN_NO_RECALL
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
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.
FILE_FLAG_OVERLAPPED
The file is being opened or created for asynchronous I/O. When the operation is complete, the event specified in the OVERLAPPED structure is set to the signaled state. Operations that take a significant amount of time to process return ERROR_IO_PENDING.
If this flag is specified, the file can be used for simultaneous read and write operations. The system does not maintain the file pointer, therefore you must pass the file position to the read and write functions in the OVERLAPPED structure or update the file pointer.
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
The file is to be accessed 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
The file is to be accessed randomly. The system can use this as a hint to optimize file caching.
FILE_FLAG_SEQUENTIAL_SCAN
The file is to be accessed sequentially from beginning to end. The system can use this as a hint to optimize file caching. If an application moves the file pointer for random access, optimum caching may not occur. However, correct operation is still guaranteed.
Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.
This flag has no effect if the file system does not support cached I/O and FILE_FLAG_NO_BUFFERING.
FILE_FLAG_WRITE_THROUGH
Write operations will not go through any intermediate cache, they will go directly to disk.
If FILE_FLAG_NO_BUFFERING is not also specified, so that system caching is in effect, then the data is written to the system cache, but is flushed to disk without delay.
If FILE_FLAG_NO_BUFFERING is also specified, so that system caching is not in effect, then the data is immediately flushed to disk without going through the system cache. The operating system also requests a write-through the hard disk cache to persistent media. However, not all hardware supports this write-through capability.
The dwFlagsAndAttributes parameter can also contain Security Quality of Service information. For more information, see Impersonation Levels. When the calling application specifies the SECURITY_SQOS_PRESENT flag, the dwFlagsAndAttributes parameter can contain one or more of the following values.
Value 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.
hTemplateFile
A 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 the template file.
When opening a new EFS-encrypted file, the file inherits the DACL from its parent directory.
Return Value
If the function succeeds, the return value is an open handle to a specified file. If a specified file exists before the function call and dwCreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS, even when the function succeeds. If a file does not exist before the call, GetLastError returns zero (0).
If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.
Remarks
Use the CloseHandle function to close an object handle that CreateFile returns.
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 are formatted for that kind of file system, a new file inherits the compression and encryption attributes of its directory.
You cannot use CreateFile to control compression on a file or directory. For more information, see File Compression and Decompression, and File Encryption.
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 object may heuristically determine and report that inheritance is in effect. For more information, see Automatic Propagation of Inheritable ACEs.
The flags FILE_FLAG_WRITE_THROUGH and FILE_FLAG_NO_BUFFERING are independent. If you specify write-through but not no-buffering, then data will be written into the file cache and will also be issued to the hardware immediately, flagged as write-through. A write-through request also causes NTFS to flush any metadata changes that result from processing the request.
Symbolic link behavior—If the call to this function creates a new file, there is no change in behavior.
If FILE_FLAG_OPEN_REPARSE_POINT is specified and:
If an existing file is opened and it is a symbolic link, the handle returned is a handle to the symbolic link.
If CREATE_ALWAYS, TRUNCATE_EXISTING, or FILE_FLAG_DELETE_ON_CLOSE are specified, the file affected is a symbolic link.
If FILE_FLAG_OPEN_REPARSE_POINT is not specified and:
If an existing file is opened and it is a symbolic link, the handle returned is a handle to the target.
If CREATE_ALWAYS, TRUNCATE_EXISTING, or FILE_FLAG_DELETE_ON_CLOSE are specified, the file affected is the target.
A multi-sector write is not guaranteed to be atomic unless you are using a transaction (that is, the handle created is a transacted handle). A single-sector write is atomic. Multi-sector writes that are cached may not always be written to the disk; therefore, specify FILE_FLAG_WRITE_THROUGH to ensure that an entire multi-sector write is written to the disk without caching.
Files
If you try to create a file on a floppy drive that does not have a floppy disk or a CD-ROM drive that does not have a CD, the system displays a message for the user to insert a disk or a CD. To prevent the system from displaying this message, call the SetErrorMode function with SEM_FAILCRITICALERRORS.
Windows Server 2003 and Windows XP/2000: If CREATE_ALWAYS and FILE_ATTRIBUTE_NORMAL are specified, CreateFile fails and sets the last error to ERROR_ACCESS_DENIED if the file exists and has the FILE_ATTRIBUTE_HIDDEN or FILE_ATTRIBUTE_SYSTEM attribute. To avoid the error, specify the same attributes as the existing file.
For more information, see Creating and Opening Files.
If you rename or delete a file and then restore it shortly afterward, the system searches the cache for file information to restore. Cached information includes its short/long name pair and creation time.
If you call CreateFile on a file that is pending deletion as a result of a previous call to DeleteFile, the function fails. The operating system delays file deletion until all handles to the file are closed. GetLastError returns ERROR_ACCESS_DENIED.
When an application creates a file across a network, it is better to use GENERIC_READ GENERIC_WRITE than touse GENERIC_WRITE alone. The resulting code is faster, because the redirector can use the cache manager and send fewer SMBs with more data. This combination also avoids an issue where writing to a file across a network can occasionally return ERROR_ACCESS_DENIED.
File Streams
On NTFS file systems, you can use CreateFile to create separate streams within a file. For more information, see File Streams.
Directories
An application cannot create a directory by using CreateFile. The application must call CreateDirectory or CreateDirectoryEx to create a directory. To open a directory by using CreateFile, use the FILE_FLAG_BACKUP_SEMANTICS flag.
When using CreateFile to open a directory during defragmentation of a FAT or FAT32 file system volume, do not specify the MAXIMUM_ALLOWED access right. Access to the directory is denied if this is done. Specify the GENERIC_READ access right instead.
Physical Disks and Volumes
You can use the CreateFile function to open a physical disk drive or a volume. The function returns a handle that can be used with the DeviceIoControl function. This enables you to access the disk partition table. However, it is potentially dangerous to do so, because an incorrect write to a disk could make its contents inaccessible. The following requirements must be met for such a call to succeed:
The caller must have administrative privileges. For more information, see Running with Special Privileges.
The dwCreationDisposition parameter must have the OPEN_EXISTING flag.
When opening a volume or floppy disk, the dwShareMode parameter must have the FILE_SHARE_WRITE flag.
When opening a physical drive x, the lpFileName string should be the following form: \\.\PhysicalDriveX. Hard disk numbers start at zero (0). The following table shows some examples of physical drive strings.
String Meaning
\\.\PhysicalDrive0 Opens the first physical drive.
\\.\PhysicalDrive2 Opens the third physical drive.
To obtain the physical drive for a volume, open a handle to the volume and call the DeviceIoControl function with IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. This control code returns the disk number of offset for each of the volume's extents; a volume can span disks.
For an example of opening a physical drive, see Calling DeviceIoControl.
When opening a volume or floppy drive, the lpFileName string should be the following form: \\.\X:. Do not use a trailing backslash, which indicates the root directory of a drive. The following table shows some examples of drive strings.
String Meaning
\\.\A: Opens drive A (floppy drive).
\\.\C: Opens drive C (volume).
You can also open a volume by referring to its volume name. For more information, see Naming a Volume.
Volume handles can be opened as noncached at the discretion of the file system, even when the noncached option is not specified in CreateFile. You should assume that all Microsoft file systems open volume handles as noncached. The restrictions on noncached I/O for files also apply to volumes.
A file system may or may not require buffer alignment even though the data is noncached. However, if the noncached option is specified when opening a volume, buffer alignment is enforced regardless of the file system on the volume. It is recommended on all file systems that you open volume handles as noncached, and follow the noncached I/O restrictions.
To read or write to the last few sectors of the volume, you must call Calling DeviceIoControl and specify FSCTL_ALLOW_EXTENDED_DASD_IO. This signals the file system driver not to perform any I/O boundary checks on partition read or write calls. Instead, boundary checks are performed by the device driver.
Changer Device
The IOCTL_CHANGER_* control codes accept a handle to a changer device. To open a changer device, use a file name of the following form: \\.\Changerx where x is a number that indicates which device to open, starting with zero (0). To open changer device zero (0) in an application that is written in C or C++, use the following file name: "\\\\.\\Changer0".
Tape Drives
You can open tape drives by using a file name of the following form: \\.\TAPEx where x is a number that indicates which drive to open, starting with tape drive zero (0). To open tape drive zero (0) in an application that is written in C or C++, use the following file name: "\\\\.\\TAPE0". For more information, see Backup.
Communications Resources
The CreateFile function can create a handle to a communications resource, such as the serial port COM1. For communications resources, the dwCreationDisposition parameter must be OPEN_EXISTING, and the template parameter must be NULL. Read, write, or read/write access can be specified, and the handle can be opened for overlapped I/O. For more information about communications, see Communications.
Consoles
The CreateFile function can create a handle to console input (CONIN$). If the process has an open handle to it as a result of inheritance or duplication, it can also create a handle to the active screen buffer (CONOUT$). The calling process must be attached to an inherited console or one allocated by the Alloc console function. For console handles, set the CreateFile parameters as follows.
Parameters Value
lpFileName Use the CONIN$ value to specify console input.
Use the CONOUT$ value to specify console output.
CONIN$ gets a handle to the console input buffer, even if the SetStdHandle function redirects the standard input handle. To get the standard input handle, use the GetStdHandle function.
CONOUT$ gets a handle to the active screen buffer, even if SetStdHandle redirects the standard output handle. To get the standard output handle, use GetStdHandle.
dwDesiredAccess GENERIC_READ GENERIC_WRITE is preferred, but either one can limit access.
dwShareMode When opening CONIN$, specify FILE_SHARE_READ. When opening CONOUT$, specify FILE_SHARE_WRITE.
If the calling process inherits the console, or if a child process should be able to access the console, this parameter must be FILE_SHARE_READ FILE_SHARE_WRITE.
lpSecurityAttributes If you want the console to be inherited, the bInheritHandle member of the SECURITY_ATTRIBUTES structure must be TRUE.
dwCreationDisposition You should specify OPEN_EXISTING when using CreateFile to open the console.
dwFlagsAndAttributes Ignored.
hTemplateFile Ignored.
The following table shows various settings of dwDesiredAccess and lpFileName.
lpFileName dwDesiredAccess Result
CON GENERIC_READ Opens console for input.
CON GENERIC_WRITE Opens console for output.
CON GENERIC_READ GENERIC_WRITE Causes CreateFile to fail; GetLastError returns ERROR_FILE_NOT_FOUND.
Mailslots
If CreateFile opens the client end of a mailslot, the function returns INVALID_HANDLE_VALUE if the mailslot client attempts to open a local mailslot before the mailslot server has created it with the CreateMailSlot function. For more information, see Mailslots.
Pipes
If CreateFile opens the client end of a named pipe, the function uses any instance of the named pipe that is in the listening state. The opening process can duplicate the handle as many times as required, but after it is opened, the named pipe instance cannot be opened by another client. The access that is specified when a pipe is opened must be compatible with the access that is specified in the dwOpenMode parameter of the CreateNamedPipe function. For more information, see Pipes.
Example Code
For an example, see Opening a File for Reading or Writing.
Requirements
Client
Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Server
Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Header
Declared in WinBase.h; include Windows.h.
Library
Use Kernel32.lib.
DLL
Requires Kernel32.dll.
Unicode
Implemented as CreateFileW (Unicode) and CreateFileA (ANSI).
