It Crashed!

Running MudOS: It Crashed!

Introduction
General Notes
Unattended operation/automation
Debugging core files
Notes for SAS/C Amiga users

Introduction

This file documents some methods of obtaining crash information which the MudOS developers may find useful in tracking down hard to reproduce crashers (serious bugs).

General Notes

Ok, if your driver crashes, and you want to be helpful, here's what you do:

1. recompile the driver with the -g flag. Turning off optimization is a good idea too. [This can be done by doing a 'make neat' (or gmake), reruning ./build.MudOS as follows: './build.MudOS debug', then recompile]
2. go to your bin dir and type 'gdb driver' where driver is the name of your driver executable
3. It should startup, etc. When it's ready, type 'run config.foo' or whatever you normally do to run the driver, with 'run' instead of the driver executable name.
4. Wait for the driver to crash (or cause it to crash, if you know how)
5. gdb should give you a prompt again. type 'where'
6. Post the output of the where command along with anything you know about where/how/why the driver crashed to the mudos-bugs@imaginary.com mailing list. Stuff like example LPC source code, a tail of driver.err and/or debug.log, etc may be helpful. In some cases the driver writes important information to those files as it goes down.

If you actually get a traceback, it makes crashes somewhere between 10-100x easier to fix (at least!). Remember to also specify your driver version (eg 0.9.19), operating system/architecture, and its version (eg SunOS 5.3).

Note: if you didn't use 'gcc', but 'cc' instead (for example), to compile the driver, you will have to use 'dbx' (if you have it). The same instructions as above apply...just replace instances of 'gdb' with 'dbx'.

Unattended operation/automation

If you want to automate the process of collecting this crash information, something you can stick this into your startmud script, read this section. Begin by creating a batchfile with the following contents:

     run config.foo >driver.err
     where

Replace 'config.foo' with the name of your config file, and 'driver.err' with whatever you've set up for redirecting the driver's stderr to. Where you have 'driver' (or whatever you named the executable) in your startmud script, use (depending on the compiler used):

     gdb -batch -x batchfile driver >report

or:

     dbx -i driver report

If/when it crashes, send us a copy of the report.

Debugging core files

This section applies to you, if the driver has crashed, leaving a core file behind. A large core file is a good sign. =) Some users or systems may set a resource limit on the size of core files, eg

    limit coredumpsize 0

preventing them from debugging from the core file. Remove the limit or skip this section. HP/Apollo (Domain OS) users may be able to use '/com/tb' to get traceback information.

Using dbx:                          Using gdb:

    dbx driver core                     gdb driver core
    where                               where
    quit                                quit

Replace 'driver' with the path of your driver executable.

Another useful command is 'print', which can be used to print the values of variables in the current function, eg

    print str

'dbx' users can also use the 'dump' command to display the names and variable values in a function, eg

    dump main >file

SAS/C (Amiga)

If you are using SAS/C, compile with Debug=Symbol and link with AddSym. It's a good to turn off optimizations with NoOpt and NoOptPeep. You can use either 'cpr' or 'tb'. For 'cpr', use:

    cpr -line -command "where -a; register" driver config.foo >report

Using 'tb' is a bit more involved. In building the driver, you must:

    slink with catch.o or catchnr.o to generate snapshot files

so that if/when the driver crashes, the 'tb' utility can be used to process the snapshot file. catch.o will ask first before creating a snapshot file, while catchnr.o will not ask -- if the system is in a bad state, and catchnr.o is unable to complete writing the snapshot file, the filesystem can be potentially corrupted. Once you have a 'Snapshot.TB' file, use:

    tb -l

to obtain detailed traceback information.