ホーム › Storage.FileSystem › CreateLogFile

CreateLogFile

関数

CLFSのログファイルを作成または開く。

DLLclfsw32.dll呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

// clfsw32.dll
#include <windows.h>

HANDLE CreateLogFile(
    LPCWSTR pszLogFileName,
    DWORD fDesiredAccess,
    FILE_SHARE_MODE dwShareMode,
    SECURITY_ATTRIBUTES* psaLogFile,
    FILE_CREATION_DISPOSITION fCreateDisposition,
    FILE_FLAGS_AND_ATTRIBUTES fFlagsAndAttributes
);

パラメーター

名前

型

方向

説明

pszLogFileName

LPCWSTR

ログの名前です。

この名前は、CreateLogFile を使用してログを作成する際に指定します。次の例は使用する形式を示しています。

log :<LogName>[::<LogStreamName>]

例えば、パス "LOG:c:\MyDirectory\MyLog" は、ファイル "c:\MyDirectory\MyLog.blf" を作成します。パス "??\LOG:\HarddiskVolume1\MyDirectory\MyLog" は、パス "\clfs\Device\HarddiskVolume1\MyDirectory\MyLog" と同様に、ファイル "\.\HarddiskVolume1\MyDirectory\MyLog.blf" を作成します。

<LogName> はファイルシステム内の有効なファイルパスに対応し、<LogStreamName> はログ内のログストリームの一意な名前です。詳細については、Log Types を参照してください。

fDesiredAccess

DWORD

返されるハンドルがログオブジェクトに対して持つアクセスの種類です。

値	意味
GENERIC_READ	オブジェクトへの読み取りアクセスを指定します。
GENERIC_WRITE	オブジェクトへの書き込みアクセスを指定します。
DELETE	ログの削除アクセスを指定します。

これらのフラグの 2 つ以上をビットごとの OR で組み合わせることで、オブジェクトに対する読み取り、書き込み、削除アクセスを組み合わせて指定できます。

注意ログを削除できるようにするには、DELETE アクセスを指定する必要があります。

Windows Server 2003 R2: このパラメーターは GENERIC_WRITE に設定する必要があります。

dwShareMode

FILE_SHARE_MODE

ファイルの共有モードです。

クライアントは、オープンハンドルを持つ以前のオープン要求で指定された任意のモードと競合する共有モードを要求することはできません。

このパラメーターがゼロで関数が成功した場合、オブジェクトは共有できず、ハンドルが閉じられるまで再度開くことはできません。

このパラメーターには、次の値を 1 つ以上指定できます。

値	意味
FILE_SHARE_DELETE	オブジェクトに対するオープン操作で削除アクセスを要求できるようにします。この値を指定しない場合、削除アクセスが要求されると、他のプロセスはオブジェクトを開くことができません。
FILE_SHARE_READ	オブジェクトに対するオープン操作で読み取りアクセスを要求できるようにします。この値を指定しない場合、読み取りアクセスが要求されると、他のプロセスはオブジェクトを開くことができません。
FILE_SHARE_WRITE	オブジェクトに対するオープン操作で書き込みアクセスを要求できるようにします。この値を指定しない場合、書き込みアクセスが要求されると、他のプロセスはオブジェクトを開くことができません。

psaLogFile

SECURITY_ATTRIBUTES*

inout

ログのセキュリティ属性を指定する SECURITY_ATTRIBUTES 構造体へのポインターです。

この構造体は、返されるハンドルが子プロセスによって継承可能かどうかを決定します。このパラメーターが NULL の場合、ハンドルは継承できません。

SECURITY_ATTRIBUTES の lpSecurityDescriptor メンバーは、新しいログハンドルのセキュリティ記述子を指定します。psaLogFile が NULL の場合、オブジェクトには既定のセキュリティ記述子が割り当てられます。ログの既定のセキュリティ記述子内のアクセス制御リスト (ACL) は、作成者のプライマリトークンまたは偽装トークンに由来します。

fCreateDisposition

FILE_CREATION_DISPOSITION

実行するアクションです。

このパラメーターには、次のいずれかの値を指定できます。

値	意味
CREATE_NEW	新しいファイルを作成します。ファイルが既に存在する場合は失敗します。
OPEN_EXISTING	既存のファイルを開きます。ファイルが存在しない場合は失敗します。
OPEN_ALWAYS	既存のファイルを開きます。ファイルが存在しない場合は作成します。

fFlagsAndAttributes

FILE_FLAGS_AND_ATTRIBUTES

ファイルのファイル属性とフラグです。

このパラメーターには、次の値を指定できます。

値

意味

FILE_ATTRIBUTE_ARCHIVE

この非エフェメラルログはアーカイブされる必要があります。

このフラグが指定されない場合、ログはアーカイブされる必要がなく、ログコンテナーをリサイクルするためのアーカイブテールも維持されません。

FILE_FLAG_OVERLAPPED

FILE_FLAG_OVERLAPPED フラグが設定されている場合、他のすべてのフラグ値は無視されます。

FILE_FLAG_OVERLAPPED を指定すると、ファイルはオーバーラップ I/O 用に開かれ、ログハンドルに対して複数の I/O 操作を実行できるようになります。ログの作成時にこのフラグが設定されている場合、そのログへのすべての非同期 I/O 呼び出しは、オーバーラップ構造体を指定し、呼び出しの遅延完了と同期する必要があります。

戻り値の型: HANDLE

公式ドキュメント

ログを作成または開きます。

戻り値

関数が成功した場合、戻り値はログへのハンドルです。

関数が失敗した場合、戻り値は INVALID_HANDLE_VALUE です。拡張エラー情報を取得するには、GetLastError を呼び出します。

次の一覧は、発生する可能性のあるエラーコードを示しています。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// clfsw32.dll
#include <windows.h>

HANDLE CreateLogFile(
    LPCWSTR pszLogFileName,
    DWORD fDesiredAccess,
    FILE_SHARE_MODE dwShareMode,
    SECURITY_ATTRIBUTES* psaLogFile,
    FILE_CREATION_DISPOSITION fCreateDisposition,
    FILE_FLAGS_AND_ATTRIBUTES fFlagsAndAttributes
);

[DllImport("clfsw32.dll", SetLastError = true, ExactSpelling = true)]
static extern IntPtr CreateLogFile(
    [MarshalAs(UnmanagedType.LPWStr)] string pszLogFileName,   // LPCWSTR
    uint fDesiredAccess,   // DWORD
    uint dwShareMode,   // FILE_SHARE_MODE
    IntPtr psaLogFile,   // SECURITY_ATTRIBUTES* in/out
    uint fCreateDisposition,   // FILE_CREATION_DISPOSITION
    uint fFlagsAndAttributes   // FILE_FLAGS_AND_ATTRIBUTES
);

<DllImport("clfsw32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CreateLogFile(
    <MarshalAs(UnmanagedType.LPWStr)> pszLogFileName As String,   ' LPCWSTR
    fDesiredAccess As UInteger,   ' DWORD
    dwShareMode As UInteger,   ' FILE_SHARE_MODE
    psaLogFile As IntPtr,   ' SECURITY_ATTRIBUTES* in/out
    fCreateDisposition As UInteger,   ' FILE_CREATION_DISPOSITION
    fFlagsAndAttributes As UInteger   ' FILE_FLAGS_AND_ATTRIBUTES
) As IntPtr
End Function

' pszLogFileName : LPCWSTR
' fDesiredAccess : DWORD
' dwShareMode : FILE_SHARE_MODE
' psaLogFile : SECURITY_ATTRIBUTES* in/out
' fCreateDisposition : FILE_CREATION_DISPOSITION
' fFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES
Declare PtrSafe Function CreateLogFile Lib "clfsw32" ( _
    ByVal pszLogFileName As LongPtr, _
    ByVal fDesiredAccess As Long, _
    ByVal dwShareMode As Long, _
    ByVal psaLogFile As LongPtr, _
    ByVal fCreateDisposition As Long, _
    ByVal fFlagsAndAttributes As Long) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CreateLogFile = ctypes.windll.clfsw32.CreateLogFile
CreateLogFile.restype = ctypes.c_void_p
CreateLogFile.argtypes = [
    wintypes.LPCWSTR,  # pszLogFileName : LPCWSTR
    wintypes.DWORD,  # fDesiredAccess : DWORD
    wintypes.DWORD,  # dwShareMode : FILE_SHARE_MODE
    ctypes.c_void_p,  # psaLogFile : SECURITY_ATTRIBUTES* in/out
    wintypes.DWORD,  # fCreateDisposition : FILE_CREATION_DISPOSITION
    wintypes.DWORD,  # fFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('clfsw32.dll')
CreateLogFile = Fiddle::Function.new(
  lib['CreateLogFile'],
  [
    Fiddle::TYPE_VOIDP,  # pszLogFileName : LPCWSTR
    -Fiddle::TYPE_INT,  # fDesiredAccess : DWORD
    -Fiddle::TYPE_INT,  # dwShareMode : FILE_SHARE_MODE
    Fiddle::TYPE_VOIDP,  # psaLogFile : SECURITY_ATTRIBUTES* in/out
    -Fiddle::TYPE_INT,  # fCreateDisposition : FILE_CREATION_DISPOSITION
    -Fiddle::TYPE_INT,  # fFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES
  ],
  Fiddle::TYPE_VOIDP)

#[link(name = "clfsw32")]
extern "system" {
    fn CreateLogFile(
        pszLogFileName: *const u16,  // LPCWSTR
        fDesiredAccess: u32,  // DWORD
        dwShareMode: u32,  // FILE_SHARE_MODE
        psaLogFile: *mut SECURITY_ATTRIBUTES,  // SECURITY_ATTRIBUTES* in/out
        fCreateDisposition: u32,  // FILE_CREATION_DISPOSITION
        fFlagsAndAttributes: u32  // FILE_FLAGS_AND_ATTRIBUTES
    ) -> *mut core::ffi::c_void;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("clfsw32.dll", SetLastError = true)]
public static extern IntPtr CreateLogFile([MarshalAs(UnmanagedType.LPWStr)] string pszLogFileName, uint fDesiredAccess, uint dwShareMode, IntPtr psaLogFile, uint fCreateDisposition, uint fFlagsAndAttributes);
"@
$api = Add-Type -MemberDefinition $sig -Name 'clfsw32_CreateLogFile' -Namespace Win32 -PassThru
# $api::CreateLogFile(pszLogFileName, fDesiredAccess, dwShareMode, psaLogFile, fCreateDisposition, fFlagsAndAttributes)

#uselib "clfsw32.dll"
#func global CreateLogFile "CreateLogFile" sptr, sptr, sptr, sptr, sptr, sptr
; CreateLogFile pszLogFileName, fDesiredAccess, dwShareMode, varptr(psaLogFile), fCreateDisposition, fFlagsAndAttributes   ; 戻り値は stat
; pszLogFileName : LPCWSTR -> "sptr"
; fDesiredAccess : DWORD -> "sptr"
; dwShareMode : FILE_SHARE_MODE -> "sptr"
; psaLogFile : SECURITY_ATTRIBUTES* in/out -> "sptr"
; fCreateDisposition : FILE_CREATION_DISPOSITION -> "sptr"
; fFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "clfsw32.dll"
#cfunc global CreateLogFile "CreateLogFile" wstr, int, int, var, int, int
; res = CreateLogFile(pszLogFileName, fDesiredAccess, dwShareMode, psaLogFile, fCreateDisposition, fFlagsAndAttributes)
; pszLogFileName : LPCWSTR -> "wstr"
; fDesiredAccess : DWORD -> "int"
; dwShareMode : FILE_SHARE_MODE -> "int"
; psaLogFile : SECURITY_ATTRIBUTES* in/out -> "var"
; fCreateDisposition : FILE_CREATION_DISPOSITION -> "int"
; fFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "clfsw32.dll"
#cfunc global CreateLogFile "CreateLogFile" wstr, int, int, sptr, int, int
; res = CreateLogFile(pszLogFileName, fDesiredAccess, dwShareMode, varptr(psaLogFile), fCreateDisposition, fFlagsAndAttributes)
; pszLogFileName : LPCWSTR -> "wstr"
; fDesiredAccess : DWORD -> "int"
; dwShareMode : FILE_SHARE_MODE -> "int"
; psaLogFile : SECURITY_ATTRIBUTES* in/out -> "sptr"
; fCreateDisposition : FILE_CREATION_DISPOSITION -> "int"
; fFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。