CreateFile
The CreateFile function creates or opens the following objects and returns a handle that can be used to access
the object:
files
pipes
mailslots
communications resources
disk devices(Windows NT only)
consoles
directories(open only)
CreateFile 函数创建或打开下列对象，并返回一个能够用来訪问这些对象的句柄。
文件
pipes
邮槽
通信资源
磁盘驱动器（仅适用于 windowsNT ）
控制台
目录（仅用于打开）
HANDLE CreateFile(
LPCTSTR lpFileName, // 指向文件名称的指针
DWORD dwDesiredAccess, // 訪问模式（写 / 读）
DWORD dwShareMode, // 共享模式
LPSECURITY_ATTRIBUTES lpSecurityAttributes, // 指向安全属性的指针
DWORD dwCreationDisposition, // 怎样创建
DWORD dwFlagsAndAttributes, // 文件属性
HANDLE hTemplateFile // 用于拷贝文件句柄
);
Parametes
參数列表
參数
类型及说明
lpFileName
String ，要打开的文件的名字
dwDesiredAccess
Long ，假设为 GENERIC_READ 表示同意对设备进行读訪问；假设为 GENERIC_WRITE 表示同意对设备进行写訪问（可组合使用）；假设为零，表示只同意获取与一个设备有关的信息
dwShareMode
Long ，零表示不共享； FILE_SHARE_READ 和 / 或 FILE_SHARE_WRITE 表示同意对文件进行共享訪问
lpSecurityAttributes
SECURITY_ATTRIBUTES ，指向一个 SECURITY_ATTRIBUTES 结构的指针，定义了文件的安全特性（假设操作系统支持的话）
dwCreationDisposition
Long ，下述常数之中的一个：
CREATE_NEW
创建文件；如文件存在则会出错
CREATE_ALWAYS
创建文件，会改写前一个文件
OPEN_EXISTING
文件必须已经存在。由设备提出要求
OPEN_ALWAYS
如文件不存在则创建它
TRUNCATE_EXISTING
讲现有文件缩短为零长度
dwFlagsAndAttributes
Long ，一个或多个下述常数
FILE_ATTRIBUTE_ARCHIVE
标记归档属性
FILE_ATTRIBUTE_COMPRESSED
将文件标记为已压缩，或者标记为文件在目录中的默认压缩方式
FILE_ATTRIBUTE_NORMAL
默认属性
FILE_ATTRIBUTE_HIDDEN
隐藏文件或目录
FILE_ATTRIBUTE_READONLY
文件为只读
FILE_ATTRIBUTE_SYSTEM
文件为系统文件
FILE_FLAG_WRITE_THROUGH
操作系统不得推迟对文件的写操作
FILE_FLAG_OVERLAPPED
同意对文件进行重叠操作
FILE_FLAG_NO_BUFFERING
禁止对文件进行缓冲处理。文件只能写入磁盘卷的扇区块
FILE_FLAG_RANDOM_ACCESS
针对随机訪问对文件缓冲进行优化
FILE_FLAG_SEQUENTIAL_SCAN
针对连续訪问对文件缓冲进行优化
FILE_FLAG_DELETE_ON_CLOSE
关闭了上一次打开的句柄后，将文件删除。特别适合暂时文件
也可在 Windows NT 下组合使用下述常数标记：
SECURITY_ANONYMOUS ， SECURITY_IDENTIFICATION ， SECURITY_IMPERSONATION ， SECURITY_DELEGATION ， SECURITY_CONTEXT_TRACKING ， SECURITY_EFFECTIVE_ONLY
hTemplateFile
Long ，假设不为零，则指定一个文件句柄。新文件将从这个文件里复制扩展属性
返回值
如运行成功，则返回文件句柄。 INVALID_HANDLE_VALUE 表示出错，会设置 GetLastError 。即使函数成功，但若文件存在，且指定了 CREATE_ALWAYS 或 OPEN_ALWAYS ， GetLastError 也会设为 ERROR_ALREADY_EXISTS
lpFileName
Pointer to a null-terminated string that specifies the name of the object(file, pipe, mailslot,
communications resource, disk device, console, or directory) to create or open.
指向一个空结尾字符串。该參数指定了用于创建或打开句柄的对象。
if *lpFileName is a path, there is a default string size limit of MAX_PATH characters, This limit is
related to how the CreateFile function parses paths.
假设 lpFileName 的对象是一个路径，则有一个最大字符数的限制。不能超过常量 (MAX_PATH). 这个限制指示了
CreateFile 函数怎样解析路径 .
dwDesiredAccess
Specifies the type of access to the object. An application can obtain read access, write access,
read-write access, or device query access, This parameter can be any combination of the following
values
指定对象的訪问方式 , 程序能够获得读訪问权 , 写訪问权 , 读写訪问权或者是询问设备 ("device query") 訪问权 .
这个參数能够是下列值的随意组合
Value( 值 ) Meaning( 含义 )
0 Specifies device query access to the object. An application can query device
attributes without accessing the device.
指定询问訪问权 . 程序能够在不直接訪问设备的情况下查询设备的属性 .
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 组合
成为 " 读写訪问权 ".
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 fro read-write access
指定写訪问权 . 能够从文件里写入数据 , 而且移动文件指针 . 能够和 GENERIC_READ 组合
成为 " 读写訪问权 ".
dwShareMode
Set of bit flags that specifies how the object can be shared, If dwShareMode is 0, the object cannot
be shared. Subsequent open operations on the object will fail, until the handle is closed.
设置位标志指明对象如休共享 . 假设參数是 0, 对象不能够共享 . 后续的打开对象的操作将会失败 , 直到该对象的句
柄关闭 .
To share the object, use a combination of one or more of the following values:
使用一个或多个下列值的组合来共享一个对象 .
Value( 值 ) Meaning( 含义 )
FILE_SHARE_DELETE WindowsNT: Subsequent open operations on the object will succeed only if
delete access is requested.
WINDOWS NT: 后续的只请求删除訪问权的打开操作将会成功 .
FILE_SHARE_READ Subsequent open operations on the object will successd only if read access
is requested.
后续的只请求读訪问权的打开操作将会成功 .
FILE_SHARE_WRITE Subsequent open operations on the object will succeed only if write access
is requested.
后续的只请求写訪问权的打开操作将会成功 .
lpSecurityAttributes
pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be
inherited by child processes, if lpSecurityAttributes is NULL, the handle cannot be inherited.
指向一个 SECURITY_ATTRIBUTES 结构的指针用于确定怎样在子进程中继承这个句柄 . 假设这个參数是 NULL,
则该句柄不可继承 .
dwCreationDisposition
Specifies which action to take on files that exist, and which action to take when files do not exist.
For more information about this parameter, see the remarks section. This parameter must be one of the
following values
指定当文件存在或者不存在时怎样动作。关于这个參数许多其他的信息，參考批注部分。这个參数必须是一个或多个
下列值。
VALUE( 值 ) Neaning( 含义 )
CREATE_NEW Creates a new file. The function fails if the specified file already exists
创建一个新文件 . 假设该文件已经存在函数则会失败 .
CREATE_ALWAYS Creates a new file. If the file exsts, the function overwrites the file and
clears the existing attributes.
创建一个新文件 . 假设该文件已经存在 , 函数将覆盖已存在的文件并清除已存在的文件属性
OPEN_EXISTING Opens the file. The function fails if the file does not exist.
See the Remarks section for a discussion of why you should use the
OPEN_EXISTING flag if you are using the CreateFile function for devices,
including the console.
打开一个文件 , 假设文件不存在函数将会失败 .
如查你使用 CreateFile 函数为设备装载控制台 . 请查看批注中的 " 为什么使用
OPEN_EXISTING 标志 " 的部分 .
OPEN_ALWAYS Opens the file, if it exsts. If the file does not exist, the function creates
the file as if dwCreationDisposition were CREATE_NEW.
假设文件存在 , 打开文件 . 假设文件不存在 , 而且參数中有 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.
打开一个文件 , 每次打开 , 文件将被截至 0 字节 . 调用进程必须用 GENERIC_WRITE 訪问模式打
开文件 . 假设文件不存在则函数就会失败 .
dwFlagsAndatributes
Specifies the file attributes and flags for the file.
为文件指定属性和标志位
Any combination of the following attributes is acceptable for the dwFlagsAndAttributes parameter,
except all other file attributes override FILE_ATTRIBUTE_NORMAL.
该參数能够接收下列属性的随意组合 . 除非其他全部的文件属性忽略 FILE_ATTRIBUTE_NORMAL.
Attribute( 属性 ) Meaning( 标志 )
FILE_ATTRIBUTE_ARCHIVE The ifle should be archived. Application use this attribute to mark
files for backup or removal.
文件将被存档 , 程序使用此属性来标志文件去备份或移除
FILE_ATTRIBUTE_HIDDEN The file is hidden. It is not to be included in an ordinary directory
listing.
文件被隐藏 , 它不会在一般目录列表中被装载 .
FILE_ATTRIBUTE_NORMAL The file has no other attributes set. This attribute is valid only if
used alone
文件沒有被设置不论什么属性 .
FILE_ATTRIBUTE_OFFLINE The data of the file is not immediately available. Indicates that the
file data has been physically moved to offline storage.
文件的数据沒有被马上用到。指出正在脱机使用该文件。
FILE_ATTRIBUTE_READONLY The file is read only.Applications can read the file but cannot write
to it or delete it
这个文件只可读取 . 程序能够读文件 , 但不能够在上面写入内容 , 也不可删除 .
FILE_ATTRIBUTE_SYSTEM The file is part of or is used exclusively by the operation system.
文件是系统的一部分 , 或是系统专用的 .
FILE_ATTRIBUTE_TEMPORARY The file is being used for temporary storage. File systems attempt
to keep all of the data in memory for quicker access rather than
flushing the data back to mass storage. A temporary file should be
deleted by the application as soon as it is no longer needed.
文件被使用后，文件系统将努力为（文件的）全部数据的迅迅訪问保持一块
内存。暂时文件应当在程序不用时及时删除。
Any combination of the following flags is acceptable for the dwFlagsAndAttributes parameter.
dwFlagAndAttributes 能够接受下列标志的随意组合。
FLAG （标志） Meaning( 含义 )
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.
指示系统通过高速缓存直接写入磁盘，
FILE_FLAG_OVERLAPPED Instructs the system to initialize the object, so that operations that
take a significant amount of time to process return ERROR_IO_PENDING.
When the operation is finished, the specified event is set to the
signaled state.
指示系统初始化对象 , 此操作将对进程设置一个引用计数并返回 ERROR_IO_PENDING.
处理完成后 , 指定对象将被设置为信号状态 .
When you specify FILE_FLAG_OVERLAPPED, the file read and write functions
must specify an OVERLAPPED structure. That is, when FILE_FLAG_OVERLAPPED
is specified, an application must perform overlapped parameter(pointing
to an OVERLAPPED structure)to the file read and write functions.
This flag also enables more than one operation to be performed
simultaneously with the handle(a simultaneous read and write operation,
for example).
当你指定 FILE_FLAG_OVERLAPPED 时 , 读写文件的函数必须指定一个 OVERLAPPED 结构 .
而且 . 当 FILE_FLAG_OVERLAPPED 被指定 , 程序必须运行重叠參数 ( 指向 OVERLAPPED
结构 ) 去进行文件的读写 .
这个标志也能够有超过一个操作去运行 .
FILE_FLAG_NO_BUFFERING Instructs the system to open the file with no intermediate buffering or
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 will take
longer, because data is not being held in the cache.
指示系统不使用高速缓冲区或缓存，当和 FILE_FLAG_OVERLAPPED 组合 , 该标志给出最
大的异步操作量 , 由于 I/O 不依赖内存管理器的异步操作 . 然而 , 一些 I/O 操作将会运行
得长一些 , 由于数据沒有控制在缓存中 .
An application must meet certain requirements when working with files
opened with FILE_FLAG_NO_BUFFERING:
当使用 FILE_FLAG_NO_BUFFERING 打开文件进行工作时 , 程序必须达到下列要求 :
File access must begin at byte offsets within the file that are
integer multiples of the volume's sector size.
文件的存取开头的字节偏移量必须是扇区尺寸的整倍数 .
File access must be for numbers of bytes that are integer
multiples of the volume's sector size. For example, if the sector
size is 512 bytes, an application can request reads and writes of
512, 1024, or 2048 bytes, but not of 335, 981, or 7171bytes.
文件存取的字节数必须是扇区尺寸的整倍数 . 比如 , 假设扇区尺寸是 512 字节
程序就能够读或者写 512,1024 或者 2048 字节 , 但不能够是 335,981 或者 7171
字节 .
buffer addresses for read and write operations must be sector
aligned(aligned on addresses in memory that are integer multiples
of the volume's sector size).
进行读和写操作的地址必须在扇区的对齐位置 , 在内存中对齐的地址是扇区
尺寸的整倍数 .
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's sector size.
一个将缓冲区与扇区尺寸对齐的途径是使用 VirtualAlloc 函数 . 它分配与操作系统
内存页大小的整倍数对齐的内存地址 . 由于内存页尺寸和扇区尺寸 --2 都是它们的幂 .
这块内存在地址中相同与扇区尺寸大小的整倍数对齐 .
An application can determine a volume's sector size by calling the
GetDiskFreeSpace function
程序能够通过调用 GetDiskFreeSpace 来确定扇区的尺寸 .
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_SEQUENTIAL_SCAN
Indicates that 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.
指定这个标志能够提高程序以顺序訪问模式读取大文件的性能 , 性能的提高在很多
程序读取一些大的顺序文件时是异常明显的 . 可是可能会有小范围的字节遗漏 .
FILE_FLAG_DELETE_ON_CLOSE Indicates that the operating system is to delete the file immediately
after all of its handles have been closed, not just the handle for which
you specified FILE_FLAG_DELETE_ON_CLOSE.
指示系统在文件全部打开的句柄关闭后马上删除文件 . 不唯独你能够指定 FILE_FLAG_DELETE_ON_CLOSE
Subsequent open requests for the file will fail, unless FILE_SHARE_DELETE
is used.
假设沒有使用 FILE_SHARE_DELETE, 后续的打开文件的请求将会失败 .
FILE_FLAG_BACKUP_SEMANTICS WINDOWS NT:Indicates that the file is being opened or created for a backup
or restore operation.The system ensures that the calling process overrides
file security checks, provided it has the necessary privileges. The
relevant privileges are SE_BACKUP_NAME and SE_RESTORE_NAME.
WINDOWS NT: 指示系统为文件的打开或创建运行一个备份或恢复操作 . 系统保证调
用进程忽略文件的安全选项 , 倘若它必须有一个特权 . 则相关的特权则是 SE_BACKUP_NAME
和 SE_RESTORE_NAME.
You can also set this flag to obtain a handle to a directory. A directory
handle can be passed to some Win32 functions in place of a file handle.
你也能够使用这个标志获得一个目录的句柄，一个目录句柄能够象一个文件句柄
一样传给某些 Win32 函数。
FILE_FLAG_POSIX_SEMANTICS Indicates that 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 such naming. Use care when using this option because
files created with this flag may not be accessible by applications written
for MS-DOS or 16-bit Windows.
指明文件符合 POSIX 标准 . 这是在 MS-DOS 与 16 位 Windows 下的标准 .
FILE_FLAG_OPEN_REPARSE_POINT Specifying this flag inhibits the reparse behavior of NTFS reparse points.
When the file is opened, a file handle is returned, whether the filter that
controls the reparse point is operational or not. This flag cannot be used
with the CREATE_ALWAYS flag.
指定这个标志制约 NTFS 分区指针 . 该标志不能够和 CREAT_ALWAYS 一起使用 .
FILE_FLAG_OPEN_NO_RECALL Indicates that the file data is requested,but it should continue to reside in
remote storage. It should not be transported back to local storage. This flag
is intended for use by remote storage systems or the Hierarchical Storage
Management system.
指明须要文件数据 , 可是将继续从远程存储器中接收 . 它不会将数据存放在本地存储器中 .
这个标志由远程存储系统或等级存储管理器系统使用 .
hTemplateFile
Specifies a handle with GENERIC_READ access to a template file. The template file supplies file attributes and
extended attributes for the file being created.
为 GENERIC_READ 訪问的模式指定一个句柄到模板文件 . 模板文件在文件開始创建后提供文件属性和扩展属性 .
Return Values
返回值
If the function succeeds, the return value is an open handle to the specified file. If the specified file exists before
the function call and dwCreation is 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.
假设函数成功 , 返回一个打开的指定文件的句柄 . 假设指定文件在函数调用前已经存在而且 dwCreation 參数是 CREATE_ALWAYS 或者
OPEN_ALWAYS, 调用 GetLastError 就会返回 ERROR_ALREADY_EXISTS( 表示函数成功 ). 假设函数文件在调用前不存在则会返回 0.
If the function fails, the return value is INVALID_HANDLE_VALUE.To get extended error information, call GetLastError.
假设函数失败 , 返会值会是 INVALID_HANDLE_VALUE. 许多其他的错误信息能够调用 GetLastError 来获得 .
