ReadLogRestartArea function

Returns the last restart area that is written successfully to the log associated with the marshaling area of WriteLogRestartArea. The function also returns a read context that allows the caller to cursor backward or forward through a log from the restart record.

This read context is useful when scanning through previous restart areas prior to the current one by invoking ReadPreviousLogRestartArea.

Syntax


BOOL WINAPI ReadLogRestartArea(
  _In_         PVOID pvMarshal,
  _Out_        PVOID *ppvRestartBuffer,
  _Out_        PULONG pcbRestartBuffer,
  _Out_        PCLFS_LSN plsn,
  _Out_        PVOID *ppvContext,
  _Inout_opt_  LPOVERLAPPED pOverlapped
);

Parameters

pvMarshal [in]

A pointer to a marshaling context that is allocated by using the CreateLogMarshallingArea function.

ppvRestartBuffer [out]

A pointer to a variable that receives a pointer to the restart data in the log I/O block.

pcbRestartBuffer [out]

A pointer to a variable that receives the amount of restart data.

plsn [out]

A pointer to a CLFS_LSN structure that receives the log sequence number (LSN) of the restart area.

ppvContext [out]

A pointer to a variable that receives a pointer to a system-allocated read context when a read is successful.

If the function defers completion of an operation, it returns a valid read-context pointer and an error status of ERROR_IO_PENDING. On all other errors, the read-context pointer is NULL. For more information about handling deferred completion of the function, see the Remarks section of this topic.

After obtaining all requested log records, the client must pass the read context to TerminateReadLog to free the associated memory. Failure to do so results in memory leakage.

Note  Common Log File System (CLFS) read contexts are not thread-safe. They should not be used by more than one thread at a time, or passed into more than one asynchronous read at a time.

pOverlapped [in, out, optional]

A pointer to an OVERLAPPED structure that is required for asynchronous operation.

This parameter can be NULL if an asynchronous operation is not used.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

The following list identifies the possible error codes:

ERROR_ACCESS_DENIED
ERROR_HANDLE_EOF
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER
ERROR_IO_DEVICE
ERROR_IO_PENDING
ERROR_LOG_BLOCKS_EXHAUSTED
ERROR_LOG_BLOCK_INCOMPLETE
ERROR_LOG_NO_RESTART

Remarks

The error message ERROR_LOG_BLOCK_INCOMPLETE is returned if the log block size specified by CreateLogMarshallingArea is not large enough to hold a complete log block.

Typically, ReadLogRestartArea is used only during client restart, either after a crash or after a normal shutdown.

If there is no restart area in the log, ReadLogRestartArea fails with the code ERROR_LOG_NO_RESTART.

If ReadLogRestartArea fails with an error code of ERROR_IO_PENDING, a pointer to a valid read context is placed in the variable pointed to by the ppvReadContext parameter.

To complete the log-record copy, the client should first synchronize its execution with deferred completion of the overlapped I/O operation by calling GetOverlappedResult, or one of the synchronization Wait Functions. For more information, see Synchronization and Overlapped Input and Output.

After ReadLogRestartArea completes asynchronously, the requested restart area is read from the disk, but a valid pointer to it is not placed in *ppvRestartBuffer.

To obtain a valid pointer, the client must call ReadPreviousLogRestartArea, which passes in the read-context pointer returned by ReadLogRestartArea.

Note  Common Log File System (CLFS) read contexts are not thread-safe. They should not be used by more than one thread at a time.

CLFS read contexts should not be passed into more than one asynchronous read at a time, or the function fails with ERROR_BUSY.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 R2 [desktop apps only]

Header

Clfsw32.h

Library

Clfsw32.lib

DLL

Clfsw32.dll

See also

CLFS_LSN
Common Log File System Functions
CreateLogFile
OVERLAPPED
ReadPreviousLogRestartArea
Synchronization and Overlapped Input and Output
WriteLogRestartArea

 

 

Community Additions

ADD
Show:
© 2014 Microsoft