IoAllocateErrorLogEntry

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.

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

Parameters

IoObject

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

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.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

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 it too large.

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

Callers of IoAllocateErrorLogEntry must be running at IRQL <= DISPATCH_LEVEL.

See Also

IO_ERROR_LOG_PACKET, IoFreeErrorLogEntry, IoWriteErrorLogEntry