ClfsWriteRestartArea function (wdm.h)

Article
02/25/2022

The ClfsWriteRestartArea routine atomically appends a new restart record to a CLFS stream, flushes the restart record to stable storage, and optionally updates the base LSN of the stream.

Syntax

CLFSUSER_API NTSTATUS ClfsWriteRestartArea(
  [in, out]       PVOID     pvMarshalContext,
  [in]            PVOID     pvRestartBuffer,
  [in]            ULONG     cbRestartBuffer,
  [in, optional]  PCLFS_LSN plsnBase,
  [in]            ULONG     fFlags,
  [out, optional] PULONG    pcbWritten,
  [out, optional] PCLFS_LSN plsnNext
);

Parameters

[in, out] pvMarshalContext

A pointer to an opaque context that represents a marshalling area associated with a CLFS stream. The caller previously obtained this pointer by calling ClfsCreateMarshallingArea.

[in] pvRestartBuffer

A pointer to a buffer that contains the data for the restart record.

[in] cbRestartBuffer

The size, in bytes, of the buffer pointed to by pvRestartBuffer. This is the size of the restart data.

[in, optional] plsnBase

A pointer to a CLFS_LSN structure that specifies a new base LSN for the stream. If this parameter is NULL, the base LSN is not changed.

[in] fFlags

This parameter must be one of the following values.

Value	Meaning
0	The restart record is placed in newly allocated space in an I/O block. The number of reserved records in the marshalling area is not changed.
CLFS_FLAG_USE_RESERVATION	The restart record is placed in previously reserved space in an I/O block. The number of reserved records in the marshalling area is reduced by one.

[out, optional] pcbWritten

A pointer to a ULONG-typed variable that receives the number of bytes actually forced to stable storage. This parameter can be NULL.

[out, optional] plsnNext

A pointer to a CLFS_LSN structure that receives the LSN of the newly written restart record.

Return value

ClfsWriteRestartArea returns STATUS_SUCCESS if it succeeds; otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

Typically ClfsWriteRestartArea is called as the last act of a client checkpoint.

ClfsWriteRestartArea is a relatively expensive operation because it causes a flush of all records currently in the marshalling area along with a flush of stream and log metadata.

At any one time, only one marshalling area should be used to write data to a stream. Having two marshalling areas writing into the stream might result in stream corruption.

If you just want to set the base LSN of a stream, use ClfsAdvanceLogBase, which does not necessarily flush any data to stable storage.

For an explanation of CLFS concepts and terminology, see Common Log File System.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Server 2003 R2, Windows Vista, and later versions of Windows.
Target Platform	Desktop
Header	wdm.h (include Wdm.h)
Library	Clfs.lib
DLL	Clfs.sys
IRQL	<= APC_LEVEL