ClearEventLog

The ClearEventLog function clears the specified event log, and optionally saves the current copy of the logfile to a backup file.

BOOL ClearEventLog(
  HANDLE hEventLog,          // handle to event log
  LPCTSTR lpBackupFileName   // name of backup file
);
 

Parameters

hEventLog

Handle to the event log to be cleared. This handle is returned by the OpenEventLog function.

lpBackupFileName

Pointer to the null-terminated string specifying the name of a file in which a current copy of the event logfile will be placed. If this file already exists, the function fails.

If the lpBackupFileName parameter is NULL, the current event logfile is not backed up.

Return Values

If the function succeeds, the return value is nonzero. The specified event log has been backed up (if lpBackupFileName is not NULL) and then cleared.

If the function fails, the return value is zero. To get extended error information, call GetLastError. The ClearEventLog function fails if the event log is empty or a file already exists with the same name as lpBackupFileName.

Remarks

After this function returns, any handles that reference the cleared event log cannot be used to read the log.

The ClearEventLog function is used to optionally back up an existing logfile of the module represented by hEventLog. The function backs up the logfile to another file, and then clears the existing logfile. The caller must have write permission for the path specified, and must also have permission to clear the current logfile.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Event Logging Overview, Event Logging Functions, OpenEventLog