CreateLogFile 函数（clfsw32.h）

项目
11/20/2024

创建或打开日志。日志可以专用或多路复用，具体取决于日志名称。使用 CloseHandle 函数关闭日志。

语法

CLFSUSER_API HANDLE CreateLogFile(
  [in]           LPCWSTR               pszLogFileName,
  [in]           ACCESS_MASK           fDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES psaLogFile,
  [in]           ULONG                 fCreateDisposition,
  [in]           ULONG                 fFlagsAndAttributes
);

参数

[in] pszLogFileName

日志的名称。

使用 CreateLogFile创建日志时指定此名称。以下示例标识要使用的格式。

日志：<LogName>[：：<LogStreamName>]

例如：路径“LOG：c：\MyDirectory\MyLog”创建文件“c：\MyDirectory\MyLog.blf”。路径“？？\LOG：\HarddiskVolume1\MyDirectory\MyLog“创建文件”\.\HarddiskVolume1\MyDirectory\MyLog.blf“，路径”\clfs\Device\HarddiskVolume1\MyDirectory\MyLog“也一样。

< LogName> 对应于文件系统中的有效文件路径，<LogStreamName> 是日志中日志流的唯一名称。有关详细信息，请参阅日志类型。

[in] fDesiredAccess

返回的句柄对日志对象的访问类型。

价值	意义
GENERIC_READ	指定对对象的读取访问权限。
GENERIC_WRITE	指定对对象的写入访问权限。
DELETE	指定日志删除访问权限

其中两个或多个标志的按位 OR 允许对对象的读取、写入和删除访问组合。

注释必须指定 DELETE 访问权限才能删除日志。

Windows Server 2003 R2：此参数必须设置为 GENERIC_WRITE。

[in] dwShareMode

文件的共享模式。

客户端无法请求与任何在具有打开句柄的以前打开请求中指定的任何模式冲突的共享模式。

如果此参数为零且函数成功，则对象无法共享，并且无法在句柄关闭之前再次打开。

此参数可以是以下一个或多个值。

价值	意义
FILE_SHARE_DELETE	对对象启用打开操作以请求删除访问权限。如果没有此值，则请求删除访问权限时，其他进程无法打开该对象。
FILE_SHARE_READ	启用对对象的打开操作以请求读取访问权限。如果没有此值，其他进程在请求读取访问权限时无法打开该对象。
FILE_SHARE_WRITE	对对象启用打开操作以请求写入访问权限。如果没有此值，其他进程在请求写入访问权限时无法打开对象。

[in, optional] psaLogFile

指向指定日志安全属性的 SECURITY_ATTRIBUTES 结构的指针。

它确定返回的句柄是否可以由子进程继承。如果此参数 NULL，则无法继承句柄。

SECURITY_ATTRIBUTES 的 lpSecurityDescriptor 成员为新日志句柄指定安全描述符。如果 psaLogFileNULL，则该对象将获取默认的安全描述符。日志的默认安全描述符中的访问控制列表（ACL）来自创建者的主令牌或模拟令牌。

[in] fCreateDisposition

要执行的操作。

此参数可以是下列值之一。

价值	意义
CREATE_NEW	创建一个新文件，如果该文件已存在，则失败。
OPEN_EXISTING	打开现有文件，如果该文件不存在，则失败。
OPEN_ALWAYS	打开现有文件，或者创建该文件（如果不存在）。

[in] fFlagsAndAttributes

文件的属性和标志。

此参数可以采用以下值。

价值	意义
FILE_ATTRIBUTE_ARCHIVE	应存档此非临时日志。如果未提供此标志，则不需要存档日志，并且不会保留存档尾部来回收日志容器。
FILE_FLAG_OVERLAPPED	如果设置了 FILE_FLAG_OVERLAPPED 标志，则忽略所有其他标志值。指定 FILE_FLAG_OVERLAPPED 意味着为重叠 I/O 打开文件，这样就可以对日志句柄执行多个 I/O 操作。如果在创建日志时设置了此标志，则对该日志的所有异步 I/O 调用都必须指定重叠的结构，并与调用的延迟完成同步。

返回值

如果函数成功，则返回值是日志的句柄。

如果函数失败，则返回值 INVALID_HANDLE_VALUE。若要获取扩展的错误信息，请调用 GetLastError。

以下列表标识可能的错误代码：

要求

要求	价值
最低支持的客户端	Windows Vista [仅限桌面应用]
支持的最低服务器	Windows Server 2003 R2 [仅限桌面应用]
目标平台	窗户
标头	clfsw32.h
库	Clfsw32.lib
DLL	Clfsw32.dll