ReserveAndAppendLog function

Reserves space for log buffers, or appends a log record to the log, or does both. The function is atomic.

Syntax


BOOL WINAPI ReserveAndAppendLog(
  _In_        PVOID             pvMarshal,
  _In_opt_    PCLFS_WRITE_ENTRY rgWriteEntries,
  _In_        ULONG             cWriteEntries,
  _In_opt_    PCLFS_LSN         plsnUndoNext,
  _In_opt_    PCLFS_LSN         plsnPrevious,
  _In_        ULONG             cReserveRecords,
  _Inout_opt_ LONGLONG          rgcbReservation[],
  _In_        ULONG             fFlags,
  _Out_opt_   PCLFS_LSN         plsn,
  _Inout_opt_ LPOVERLAPPED      pOverlapped
);

Parameters

pvMarshal [in]

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

rgWriteEntries [in, optional]

A pointer to an array of CLFS_WRITE_ENTRY buffers to be marshaled into one record.

This parameter is ignored if the cWriteEntries parameter is zero.

cWriteEntries [in]

The number of write entries in the rgWriteEntries array.

If this value is nonzero, you must specify a buffer in the rgWriteEntries parameter.

plsnUndoNext [in, optional]

A pointer to a CLFS_LSN structure that specifies the log sequence number (LSN) of the next record in the undo-chain.

plsnPrevious [in, optional]

A pointer to a CLFS_LSN structure that specifies the LSN of the previous record in the previous-chain.

cReserveRecords [in]

The number of record sizes in the rgcbReservation array.

rgcbReservation [in, out, optional]

A pointer to an array of reservation sizes for each record that the cReserveRecords parameter specifies.

This parameter is ignored if the cReserveRecords parameter is zero. If a reservation size is negative, a reservation of that size is released.

The actual space that is reserved for each record, including required overhead, is returned in the individual array elements on successful completion. These values can be passed to the FreeReservedLog function to adjust space that is reserved in the marshaling area.

fFlags [in]

The flags that specify the behavior of this function.

One or more of the following values can be combined.

ValueMeaning
CLFS_FLAG_FORCE_APPEND

Assigns a physical location for all appended records in a log that have not been previously assigned a physical location.

All these records are made available for reading from other marshaling contexts.

CLFS_FLAG_FORCE_FLUSH

Assigns a physical location for all appended records in a log that have not been previously assigned a physical location.

All these records are made available for reading from other marshaling contexts. Then, the records are flushed to disk.

CLFS_FLAG_NO_FLAGS

Assigns no flags.

CLFS_FLAG_USE_RESERVATION

Appends the current record by using the space that is reserved in the marshaling area.

 

plsn [out, optional]

A pointer to a CLFS_LSN structure that receives the LSN of the appended record.

pOverlapped [in, out, optional]

A pointer to an OVERLAPPED structure.

This parameter can be NULL if 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 the GetLastError function.

The following list identifies the possible error codes:

ERROR_ACCESS_DENIED
ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER
ERROR_INVALID_USER_BUFFER
ERROR_IO_DEVICE
ERROR_IO_PENDING
ERROR_LOG_FULL
ERROR_LOG_RECORDS_RESERVED_INVALID
ERROR_LOG_RESERVATION_INVALID
ERROR_LOG_SPACE_RESERVED_INVALID
ERROR_MORE_DATA
ERROR_NO_SYSTEM_RESOURCES

Remarks

The LSN that is returned by the ReserveAndAppendLog function is not necessarily the next LSN that is used. The LSN that is returned is an estimate of the next LSN, and it varies based on which flags are specified by the fFlags parameter. The LSN that is returned can be used when moving the base tail. This LSN is invalidated by the next call to this function.

If the ReserveAndAppendLog function returns ERROR_LOG_FILE_FULL, there is no more space in the log. This can be resolved in one of the following ways:

  • Free any unneeded reservations.
  • Advance the base LSN or the log archive tail, or both, to recycle containers.
  • Add containers to the log.
The CLFS Management API also provides a way to handle scenarios involving full logs.

If the ReserveAndAppendLog function is called with a valid pOverlapped structure and the log handle is created with the overlapped option, then if a call to this function fails with an error code of ERROR_IO_PENDING, a pointer to a valid read context is placed in the variable that is 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 using the GetOverlappedResult function, or one of the synchronization Wait Functions. For more information, see Synchronization and Overlapped Input and Output.

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
CLFS_WRITE_ENTRY
Common Log File System Functions
OVERLAPPED

 

 

Community Additions

ADD
Show: