log-bug-form

log-bug-form Function

Summary

Writes a log of an error. This is useful in an application's error handlers.

Package

dbg

Signature

log-bug-form description &key log-file message-stream => path

Arguments

`description`⇩	A string.
`log-file`⇩	A pathname designator.
`message-stream`⇩	An output stream, `t` or `nil`.

Values

path

A pathname.

Description

The function log-bug-form is a simple interface for writing a log of an error. Your application's error handlers can call it.

log-bug-form opens the file log-file for output. It writes the current date followed by a bug form. The bug form contains description, and debugging information generated by the system. When it finishes it writes to the stream message-stream a single line reporting that a bug form was written.

If log-file is supplied it must be a valid path, and it is used to open the file. The default value of log-file is the value returned by executable-log-file.

log-bug-form calls ensure-directories-exist before opening the log file, therefore so the directory where log-file is written does not need to exist before log-bug-form is called.

If message-stream is t the message is written to standard output. If message-stream is a stream the message is written to it, and if message-stream is nil then no message is written. message-stream defaults to the value of *error-output*.

If there is an error during the operation, log-bug-form silently fails and returns nil.

On success log-bug-form returns the path where the log file was written.

See also the section "Reporting bugs" in the Release Notes and Installation Guide.

Notes

log-bug-form is invoked automatically if the debugger decides to use the console (the terminal) rather than use the LispWorks IDE debugging tools. This means that after such an error the user can always find a bug form in the default log file, which can be found by using executable-log-file.

log-bug-form always appends, so if it is called frequently the log file grows continuously. You may need to clear it periodically. It may be a good idea to move the file rather than delete it, so a record of errors remains.

When editing the log file it should be noted that each bug form is preceded by the time it was written, and that the bug forms are in chronological order. That means that the interesting bug form is most often the last one in the file.

Compatibility notes

In LispWorks 7.0 and earlier, message-stream defaulted to the value of *debug-io*, but this was not documented.