【C语言】CreateFile函数用法介绍

目录

一、函数原型与基本功能

二、参数详解

1. lpFileName（文件路径）

2. dwDesiredAccess（访问权限）

补充说明

3. dwShareMode（共享模式）

5. dwCreationDisposition（创建策略）

6. dwFlagsAndAttributes（属性标记）

7. hTemplateFile（模板文件句柄）

三、返回值与错误处理

四、使用场景示例

场景1：创建新文本文件

场景2：异步读取串口数据

五、扩展注意事项

---

        CreateFile函数是Windows API中用于文件/设备操作的核心接口，支持创建、打开文件及多种I/O设备（如串口、管道、磁盘等）。本文将详细介绍。

一、函数原型与基本功能

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

        该函数返回对象的操作句柄，失败时返回INVALID_HANDLE_VALUE（需用GetLastError()获取错误码）。

二、参数详解

1. lpFileName（文件路径）

• 作用：指定操作对象的名称（文件、设备、命名管道等）
• 特性：
  • 支持绝对/相对路径，可用/或\分隔符
  • 最大长度限制为MAX_PATH（260字符），Unicode版本可突破此限制
  • 特殊设备名如COM1（串口）、LPT1（并口）需遵循MS-DOS设备命名规则

2. dwDesiredAccess（访问权限）

        以下是 CreateFile 函数中 dwDesiredAccess 参数的可能值、用途、适用场景及组合使用的详细表格总结：

---

参数值	用途	适用场景	组合使用示例
0	仅允许查询元数据（如属性、大小），不进行实际读写操作	获取文件信息（GetFileSize、GetFileTime）时无需读写权限	单独使用
GENERIC_READ	允许读取文件或设备数据，支持移动文件指针	读取文件内容（ReadFile）、查看日志、复制文件	GENERIC_READ | GENERIC_WRITE（读写权限组合）
GENERIC_WRITE	允许写入数据，支持移动文件指针或调整文件大小	写入文件（WriteFile）、修改设备配置（如串口通信）	GENERIC_READ | GENERIC_WRITE（常见组合）、GENERIC_WRITE | GENERIC_ALL
GENERIC_EXECUTE	保留值，通常用于可执行文件或驱动程序的执行权限（需设备支持）	注册表操作、可执行文件加载（实际文件操作中较少使用）	通常单独使用，需参考具体设备文档
GENERIC_ALL	授予完全控制权限（读、写、执行、删除），需配合安全描述符使用	管理员操作（修改系统文件、磁盘格式化）	单独使用或与 0 组合（查询元数据 + 完全控制）

---

补充说明

1. 权限冲突：若请求的访问权限与 dwShareMode 参数指定的共享模式冲突，函数将返回 ERROR_SHARING_VIOLATION。
2. 设备兼容性：如串口设备通常需同时指定 GENERIC_READ \| GENERIC_WRITE 以支持双向通信。
3. 特殊权限要求：GENERIC_ALL 需管理员权限或安全描述符支持，否则可能失败。

3. dwShareMode（共享模式）

控制其他进程的并发访问权限：

值	说明
FILE_SHARE_READ	允许其他进程读取
FILE_SHARE_WRITE	允许其他进程写入
FILE_SHARE_DELETE	允许其他进程删除或重命名（需NTFS支持）3
0	独占模式，阻止其他进程访问

4. lpSecurityAttributes（安全属性）

结构体：

typedef struct _SECURITY_ATTRIBUTES {
  DWORD  nLength;
  LPVOID lpSecurityDescriptor;
  BOOL   bInheritHandle;
} SECURITY_ATTRIBUTES;

作用：

• bInheritHandle：控制句柄是否被子进程继承
• lpSecurityDescriptor：设置NTFS权限（需管理员权限）

5. dwCreationDisposition（创建策略）

决定文件存在与否时的处理方式：

值	行为
CREATE_NEW	新建文件，若存在则失败
CREATE_ALWAYS	覆盖已有文件（清空属性）
OPEN_EXISTING	打开已存在文件（不存在则失败）
OPEN_ALWAYS	文件存在时打开，否则创建
TRUNCATE_EXISTING	截断已有文件（需GENERIC_WRITE权限）

6. dwFlagsAndAttributes（属性标记）

包含文件属性与操作标志的位组合：

• 常见文件属性：

  属性	说明
  FILE_ATTRIBUTE_HIDDEN	隐藏文件
  FILE_ATTRIBUTE_READONLY	只读文件
  FILE_ATTRIBUTE_TEMPORARY	临时文件（优先内存缓存）1

• 操作标志：

  标志	说明
  FILE_FLAG_OVERLAPPED	启用异步I/O操作
  FILE_FLAG_DELETE_ON_CLOSE	关闭后自动删除

7. hTemplateFile（模板文件句柄）

• 作用：复制已有文件的扩展属性（如创建时间、压缩标志）
• 限制：仅当dwCreationDisposition为CREATE_NEW或OPEN_ALWAYS时生效8

三、返回值与错误处理

1. 成功时：返回有效的句柄（需用CloseHandle()关闭）
2. 失败时：返回INVALID_HANDLE_VALUE（值为-1）
   • 典型错误码：

     错误码	说明
     ERROR_FILE_NOT_FOUND	文件不存在且未指定创建策略
     ERROR_ACCESS_DENIED	权限不足或文件被占用
     ERROR_SHARING_VIOLATION	共享模式与其他进程冲突3

四、使用场景示例

场景1：创建新文本文件

HANDLE hFile = CreateFile(
  L"example.txt",              // 文件名
  GENERIC_WRITE,              // 写权限
  0,                          // 独占模式
  NULL,                       // 默认安全属性
  CREATE_ALWAYS,              // 覆盖创建
  FILE_ATTRIBUTE_NORMAL,      // 普通文件
  NULL
);

场景2：异步读取串口数据

HANDLE hCom = CreateFile(
  L"COM1",                    // 串口设备
  GENERIC_READ | GENERIC_WRITE,
  0,
  NULL,
  OPEN_EXISTING,
  FILE_FLAG_OVERLAPPED,       // 异步模式
  NULL
);

五、扩展注意事项

1. 句柄泄漏：必须通过CloseHandle()释放资源，否则导致系统资源耗尽
2. 路径规范化：建议使用\\?\前缀绕过MAX_PATH限制（仅Unicode版本）
3. 事务操作：需使用CreateFileTransacted()实现原子文件操作3
4. 设备兼容性：部分标志（如FILE_FLAG_NO_BUFFERING）对物理磁盘有特殊要求

（完整参数列表及系统级限制可参考Microsoft官方文档）