Expand Minimize

IoAllocateErrorLogEntry routine

The IoAllocateErrorLogEntry routine allocates an error log entry, and returns a pointer to the packet that the caller uses to supply information about an I/O error.

Syntax


PVOID IoAllocateErrorLogEntry(
  _In_  PVOID IoObject,
  _In_  UCHAR EntrySize
);

Parameters

IoObject [in]

Pointer to a device object representing the device on which an I/O error occurred, or to a driver object representing the driver that found an error.

EntrySize [in]

Specifies the size, in bytes, of the error log entry to be allocated. This value cannot exceed ERROR_LOG_MAXIMUM_SIZE.

Warning  EntrySize is a UCHAR value. If you specify a larger value, the compiler will silently truncate that value to a (wrong) UCHAR.

Return value

IoAllocateErrorLogEntry returns a pointer to the error log entry, or NULL if a log entry could not be allocated.

Remarks

The driver must first fill in the packet with information about the error, then call IoWriteErrorLogEntry to post the entry to the error log. The error log entry buffer is automatically freed once the log entry is recorded. Entry buffers that are not going to be written to the log can be freed by using IoFreeErrorLogEntry.

An error log entry consists of a variable-length IO_ERROR_LOG_PACKET structure, possibly followed by one or more zero-counted Unicode strings. The Event Viewer inserts these strings into the error message it displays for the entry. IO_ERROR_LOG_PACKET contains one variable-length member, the DumpData member. Thus, the value for EntrySize must be sizeof(IO_ERROR_LOG_PACKET) + size of the DumpData member + combined size of any driver-supplied insertion strings.

Drivers should check that the value for EntrySize is less than ERROR_LOG_MAXIMUM_SIZE before calling IoAllocateErrorLogEntry. Since EntrySize is declared as a UCHAR, and the compiler will silently truncate any value too big to fit into a UCHAR, the routine itself cannot reliably detect if the passed value is too large.

Drivers must not treat IoAllocateErrorLogEntry returning NULL as a fatal error. The driver must continue to function normally, regardless of whether it can log errors.

Requirements

Version

Available in Windows 2000 and later versions of Windows.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

<= DISPATCH_LEVEL

See also

IO_ERROR_LOG_PACKET
IoFreeErrorLogEntry
IoWriteErrorLogEntry

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.