{"id":227,"date":"2007-09-25T02:26:41","date_gmt":"2007-09-25T02:26:41","guid":{"rendered":"https:\/\/driverentry.com.br\/en\/2007\/09\/25\/try-except-finally-and-iowriteerrorlogentry-part-1\/"},"modified":"2026-07-27T20:44:45","modified_gmt":"2026-07-27T20:44:45","slug":"try-except-finally-and-iowriteerrorlogentry-part-1","status":"publish","type":"post","link":"https:\/\/driverentry.com.br\/en\/2007\/09\/25\/try-except-finally-and-iowriteerrorlogentry-part-1\/","title":{"rendered":"Try, Except, Finally and IoWriteErrorLogEntry (Part 1)"},"content":{"rendered":"
\"\"<\/a><\/div>\n

Most of you have already known about exception handling in C<\/a>. Knowing that the C Run Time Kernel <\/em>does not support exception handling in C++<\/a>, the exception handling in C fits us like a glove. Exceptions do not always mean that a critical error has occurred, but regardless, it is essential to treat them. An unhandled exception in kernel means blue screen<\/a>. In the case of an unexpected exception, such as an Access Violation<\/strong>, using exception handlers could prevent the system from a blue finish. That’s great, congratulations, one more life saved, but we must not forget that there had been an unexpected exception. This post will not mention how to use exception handlers in details, but it will talk about how we can report such events to the system administrator.<\/p>\n

A Typical Exception Handling<\/h3>\n

For those who are just waking up right now, I’ll just give you a brief description of exception handling in the source below. The details are in the reference. The following source was taken from one of the examples<\/a> available on this blog. This feature can save us from a merciless blue screen whenever “a loser” who calls this function, passes an invalid string as a source of duplication.<\/p>\n

\n
\/****<\/span><\/pre>\n
***     DupString<\/span><\/pre>\n
**<\/span><\/pre>\n
**      This routine receives a Unicode String and duplicates it.<\/span><\/pre>\n
**      The resulting string should be released<\/span><\/pre>\n
**      using the ExFreePool routine.<\/span><\/pre>\n
*\/<\/span><\/pre>\n
 <\/pre>\n
NTSTATUS<\/pre>\n
DupString(IN PUNICODE_STRING   pusSource,<\/pre>\n
          OUT PUNICODE_STRING  pusTarget)<\/pre>\n
{<\/pre>\n
    NTSTATUS    nts = STATUS_SUCCESS;<\/pre>\n
 <\/pre>\n
    __try<\/span><\/pre>\n
    {<\/pre>\n
        __try<\/span><\/pre>\n
        {<\/pre>\n
            \/\/-f--> Initializes the target<\/span><\/pre>\n
            pusTarget->Buffer = NULL;<\/pre>\n
 <\/pre>\n
            \/\/-f--> Allocates the target buffer<\/span><\/pre>\n
            if<\/span> (!(pusTarget->Buffer = (PWSTR)ExAllocatePool(PagedPool,<\/pre>\n
                                                            pusSource->Length)))<\/pre>\n
                ExRaiseStatus(STATUS_INSUFFICIENT_RESOURCES);<\/pre>\n
 <\/pre>\n
            \/\/-f--> Copies the buffer<\/span><\/pre>\n
            RtlCopyMemory(pusTarget->Buffer,<\/pre>\n
                          pusSource->Buffer,<\/pre>\n
                          pusSource->Length);<\/pre>\n
 <\/pre>\n
            \/\/-f--> Copies the buffer legths<\/span><\/pre>\n
            pusTarget->MaximumLength = pusTarget->Length = pusSource->Length;<\/pre>\n
        }<\/pre>\n
        __finally<\/span><\/pre>\n
        {<\/pre>\n
            \/\/-f--> If something gets wrong, we must release the target buffer.<\/span><\/pre>\n
            if<\/span> (AbnormalTermination())<\/pre>\n
                if<\/span> (pusTarget->Buffer)<\/pre>\n
                    ExFreePool(pusTarget->Buffer);<\/pre>\n
        }<\/pre>\n
    }<\/pre>\n
    __except<\/span>(EXCEPTION_EXECUTE_HANDLER)<\/pre>\n
    {<\/pre>\n
        nts = GetExceptionCode();<\/pre>\n
 <\/pre>\n
        DbgPrint(\"DupString >> An exception occourred at \"<\/span>__FUNCTION__<\/pre>\n
                 \" with status 0x%08x.\\n\"<\/span>, nts);<\/pre>\n
 <\/pre>\n
        ASSERT(FALSE);<\/pre>\n
    }<\/pre>\n
    return<\/span> nts;<\/pre>\n
}<\/pre>\n<\/div>\n
Note that there are two blocks of execution. The outermost is the one, which will deal with unhandled exceptions, and the innermost the one, which will deal with resource releasing. The exception handler block will executes the __except <\/strong>block when any exception is thrown from the inside of __try<\/strong> block. This will give us the opportunity to find out what happened and, in some cases, to request that the instruction causing the exception is re-executed. The completion __finally<\/strong> block is executed when the thread goes out of the main block, either by reaching the block’s end, for a return, for a goto out of the block, or even an exception that was thrown. The __finally<\/strong> block is always executed. This gives us the opportunity to release any resource that has been pending during the execution of the block. Taken it together, we can imagine the following situation: suppose the function RtlCopyMemory()<\/a> throw an exception. In this case, the __except<\/strong> block will run, but for this to occur, the execution flow will leave the inner block as well, thus causing the __finally<\/strong> block execution.<\/p>\n
Within each handler, there is a special function call. Inside __except,<\/strong> we have GetExceptionCode()<\/a>, which returns us the exception code that was thrown. This function can only be called within this context. Also note that, within __finally<\/strong> block, there is a call to the AbnormalTermination()<\/a> function which indicates that the block was not executed until reaching its end. In our example, we use this function to determine that something wrong should have happened and it is necessary to release the buffer which would be returned to the calling function. Anyway, check out the reference for a complete description of these resources.<\/p>\n
The main point here to note is the ASSERT<\/a> at the end of the __except <\/strong>block. If this source is compiled in Checked<\/a>, the ASSERT<\/strong> will cause a prompt in the debugger. If there is no debugger attached to the system, then a blue screen will appear. That’s because this macro will throw a break <\/em>exception to the debugger but, as the debugger will not be there to handle this exception, figure it out. When compiled in Free<\/em>, the ASSERT<\/strong> macro is translated into nothing: our function will handle the exception gracefully and it will return the exception code to the calling function. How sweet but, when will is the administrator going to know?<\/strong><\/p>\n
A Life Sign<\/h3>\n
The standard way to leave this signal is writing in the system event log. What is this?<\/strong> This link<\/a> can give you detailed information about the system event logs. To write a record in this list from the kernel, we initially must allocate the buffer that will house all the information record using the IoAllocateErrorLogEntry()<\/a> function.<\/p>\n
\n
PVOID <\/pre>\n
  IoAllocateErrorLogEntry(<\/pre>\n
    IN PVOID  IoObject,<\/pre>\n
    IN UCHAR  EntrySize<\/pre>\n
    );<\/pre>\n<\/div>\n
The pointer returned by this function, although being the type PVOID<\/strong>, points out to an IO_ERROR_LOG_PACKET<\/strong> structure, which has variable size depending on the information that composes it. This structure is used to package all the event data that will be logged.<\/p>\n
\n
typedef<\/span> struct<\/span> _IO_ERROR_LOG_PACKET<\/pre>\n
{<\/pre>\n
    UCHAR MajorFunctionCode;<\/pre>\n
    UCHAR RetryCount;<\/pre>\n
    USHORT DumpDataSize;<\/pre>\n
    USHORT NumberOfStrings;<\/pre>\n
    USHORT StringOffset;<\/pre>\n
    USHORT EventCategory;<\/pre>\n
    NTSTATUS ErrorCode;<\/pre>\n
    ULONG UniqueErrorValue;<\/pre>\n
    NTSTATUS FinalStatus;<\/pre>\n
    ULONG SequenceNumber;<\/pre>\n
    ULONG IoControlCode;<\/pre>\n
    LARGE_INTEGER DeviceOffset;<\/pre>\n
    ULONG DumpData[1<\/span>];<\/pre>\n
 <\/pre>\n
} IO_ERROR_LOG_PACKET, *PIO_ERROR_LOG_PACKET;<\/pre>\n<\/div>\n
Although this structure has three kilograms of members, you won’t need to fill most of them up. Then, the next step is to pass the structure to the IoWriteErrorLogEntry()<\/a> function and that is it.<\/p>\n
\n
VOID <\/pre>\n
  IoWriteErrorLogEntry(<\/pre>\n
    IN PVOID  ElEntry<\/pre>\n
    );<\/pre>\n<\/div>\n
It is not that easy<\/h3>\n
So, is it just to allocate the structure, initialize it, call the function of writing and all is done?<\/strong> This question is simply funny. Not long ago, I was in Porto Alegre, and there someone told me that when one explain something starting with “It’s just…”<\/em>, the actual work is five times bigger than the one explained. Let’s start writing that famous phrase “Hello World” <\/em>to see the size of the mess!<\/p>\n
Well… Where do I put error message? Oh yeah, that’s right, into the message file<\/strong>. Unlikely log files we usually do in applications, the messages are not passed directly to the writing function. Instead, the ErrorCode member of the IO_ERROR_LOG_PACKET<\/strong> structure receives a handle to the message which will be displayed. When the IoWriteErrorLogEntry()<\/em> function is called, it puts the packet in a list in memory. Later, this package is written to the system events log file. The EventViewer<\/a>, the software used to view such events, gets the message identifier contained in the package. With this handle, it finds the string that will be stored in a separated module. This module can be your own driver or a DLL. Thus, this string is read and displayed to the user’s module. Phew!<\/p>\n
Huh? Who? When? Where?<\/strong> We will rely on the simplest driver example we have<\/a> to add these features. Let’s start composing the module writing messages to a text file that takes the  .mc <\/strong>extension. This text file will be compiled by the Message Compiler<\/a>. This compilation will generate the resource file containing strings along with the header file that will refer to certain created symbols. See the template message file below:<\/p>\n
\n
MessageIdTypedef = NTSTATUS<\/pre>\n
 <\/pre>\n
SeverityNames =<\/pre>\n
(<\/pre>\n
    Success         = 0x0:STATUS_SEVERITY_SUCCESS<\/pre>\n
    Informational   = 0x1:STATUS_SEVERITY_INFORMATIONAL<\/pre>\n
    Warning         = 0x2:STATUS_SEVERITY_WARNING<\/pre>\n
    Error           = 0x3:STATUS_SEVERITY_ERROR<\/pre>\n
)<\/pre>\n
 <\/pre>\n
FacilityNames =<\/pre>\n
(<\/pre>\n
    System          = 0x0<\/pre>\n
    DriverEntryLogs = 0x2A:DRIVERENTRY_FACILITY_CODE<\/pre>\n
)<\/pre>\n
 <\/pre>\n
LanguageNames =<\/pre>\n
(<\/pre>\n
    Portuguese  = 0x0416:msg00001<\/pre>\n
    English     = 0x0409:msg00002<\/pre>\n
)<\/pre>\n
 <\/pre>\n
MessageId = 0x0001<\/pre>\n
Facility = DriverEntryLogs<\/pre>\n
Severity = Informational<\/pre>\n
SymbolicName = EVT_HELLO_MESSAGE<\/pre>\n
 <\/pre>\n
Language = Portuguese<\/pre>\n
\"Ola mundo!\"<\/pre>\n
.<\/pre>\n
Language = English<\/pre>\n
\"Hello world!\"<\/pre>\n
.<\/pre>\n<\/div>\n
Notice that we have the same message in several languages. What a fancy thing, uh?<\/strong> Save this file with the name of LogMsgs.mc<\/strong>. You can name it of your choice, but remember that this name will be repeated at the generated files. To compile this file, just put it in the list of sources to be compiled, which is in the sources<\/a> of your project file, as it is shown below. If you decide the messages should be contained within the driver itself, then you need to add the LogMsgs.rc<\/strong> file that will be generated by the Message Compiler<\/strong>.<\/p>\n
\n
TARGETNAME=Useless<\/pre>\n
TARGETPATH=obj<\/pre>\n
TARGETTYPE=DRIVER<\/pre>\n
 <\/pre>\n
SOURCES=LogMsgs.mc\\<\/pre>\n
        Useless.c \\<\/pre>\n
        LogMsgs.rc<\/pre>\n<\/div>\n
Once compiled, the files LogMsgs.rc<\/strong> and LogMsgs.h<\/strong> will be generated. The header file defines the error codes defined at the message file and should be included in the sources files that will make calls for log creation. Watch an excerpt of this file that was generated automagically<\/em>.<\/p>\n
\n
\/\/<\/span><\/pre>\n
\/\/ MessageId: EVT_HELLO_MESSAGE<\/span><\/pre>\n
\/\/<\/span><\/pre>\n
\/\/ MessageText:<\/span><\/pre>\n
\/\/<\/span><\/pre>\n
\/\/  \"Ola mundo!\"<\/span><\/pre>\n
\/\/<\/span><\/pre>\n
#define<\/span> EVT_HELLO_MESSAGE                ((NTSTATUS)0x402A0001L<\/span>)<\/pre>\n<\/div>\n
Finally we can write the code lines that will use all of this stuff we have created.<\/p>\n
\n
#include<\/span>  <\/span><\/pre>\n
#include<\/span> \"LogMsgs.h\"<\/span><\/pre>\n
 <\/pre>\n
\/****<\/span><\/pre>\n
***     DriverEntry <\/span><\/pre>\n
**<\/span><\/pre>\n
**      That's our driver entry point, everything starts from here,<\/span><\/pre>\n
**      and atfer gets worse and worse...<\/span><\/pre>\n
*\/<\/span><\/pre>\n
 <\/pre>\n
NTSTATUS DriverEntry(IN PDRIVER_OBJECT  pDriverObject,<\/pre>\n
                     IN PUNICODE_STRING pusRegistryPath)<\/pre>\n
{<\/pre>\n
    PIO_ERROR_LOG_PACKET    pLogPacket;<\/pre>\n
 <\/pre>\n
    \/\/-f--> Allocates an entry to the event.<\/span><\/pre>\n
    pLogPacket = IoAllocateErrorLogEntry(pDriverObject,<\/pre>\n
                                         sizeof<\/span>(IO_ERROR_LOG_PACKET));<\/pre>\n
 <\/pre>\n
    \/\/-f--> Inicializes all the structure<\/span><\/pre>\n
    RtlZeroMemory(pLogPacket, sizeof<\/span>(IO_ERROR_LOG_PACKET));<\/pre>\n
 <\/pre>\n
    \/\/-f--> Puts up the desired message<\/span><\/pre>\n
    pLogPacket->ErrorCode = EVT_HELLO_MESSAGE;<\/pre>\n
 <\/pre>\n
    \/\/-f--> Sends the entry to the system event list<\/span><\/pre>\n
    IoWriteErrorLogEntry(pLogPacket);<\/pre>\n
 <\/pre>\n
    \/\/-f--> Phew, we got to be here; that makes<\/span><\/pre>\n
    \/\/      a success returning code to the system be worthy!<\/span><\/pre>\n
    return<\/span> STATUS_SUCCESS;<\/pre>\n
}<\/pre>\n<\/div>\n
Is everything done now?<\/h3>\n
From the driver viewpoint, it is all already done. The driver can now be compiled, loaded and thus able to create the entry in the log, carrying the message number to be displayed by EventViewer<\/em>. After executing the driver, we can open the EventViewer;<\/em> and it is able to find the entry generated by our driver, and then to see the message.<\/p>\n
\"\"<\/div>\n
Oops! We still have to tell EventViewer<\/em> what is the responsible module for storing the strings. In our case, the messages are in the driver itself. To achieve this, we must add a key with the name of our driver in the EventLog<\/a><\/em> registry key<\/a>. Within this key, we still have to create two values indicating the module path which contains the messages and what kinds of events our driver can generate. Look at carefully the registry path in the figure below.<\/p>\n
\"\"<\/div>\n
Once we set the values described above in the registry, just reopen the same event so that the message is displayed as it should be. Remember that the driver does not need to send the event again for the message to be displayed correctly. The driver sends only one entry with the message identifier. This was already done regardless of the message module has been configured. In the figure below, we can see the messages in Portuguese and English, depending on the language of the operating system. What a cute!<\/p>\n
\"\"<\/div>\n
As this post is getting bigger than I had expected (for change), I will divide it into parts. I still want to comment on how to use its input parameters to clarify the doubts that some of you may be asking now: “If the log entry is initially in a linked list, and only after a time that is actually going to the disk, can entries be lost if the machine falls in this interval? “<\/em>.<\/p>\n
Is the butler really culprit? Is the Matrix<\/a> inside another Matrix? Does Tostines sell more because it’s fresh, or is it fresh because it sells more? Do not miss it!<\/p>\n
CYA … \ud83d\ude42<\/div>\n","protected":false},"excerpt":{"rendered":"
Most of you have already known about exception handling in C. Knowing that the C Run Time Kernel does not support exception handling in C++, the exception handling in C fits us like a glove. Exceptions do not always mean that a critical error has occurred, but regardless, it is essential to treat them. An […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"pagelayer_contact_templates":[],"_pagelayer_content":"","footnotes":""},"categories":[1],"tags":[],"class_list":["post-227","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/227","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/comments?post=227"}],"version-history":[{"count":2,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/227\/revisions"}],"predecessor-version":[{"id":300,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/227\/revisions\/300"}],"wp:attachment":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/media?parent=227"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/categories?post=227"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/tags?post=227"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}