Coding Guidelines/Debugging Functions

The most common function for debugging, used throughout the Amanda codebase, is dbprintf. Its arguments are identical to printf, but its output goes to the debug file. Its first argument should end in a newline, and should be translated if it contains any english text. Example:

if (fd < 0)
  dbprintf(_("Could not open '%s': %s\n"), filename, strerror(errno));

In this example, the format string is not translated, since it does not contain any text worthy of translation:

dbprintf("%s: %s\n", device->name, device->errmsg);

Using Debugging in Executables

When an executable starts, it needs to set up debugging. Early in its main, it should call set_pname to set the process name correctly, then call dbopen with an appropriate subdirectory name (typically one of the DBG_SUBDIR_* constants). If the executable runs in the context of a particular Amanda configuration, it should call

dbrename(config_name, DBG_SUBDIR_SERVER);

to move the debugging information into the relevant subdirectory.

When the executable finishes, it should call dbclose to flush and close any open debug files.

Conditional Debugging

Some parts of Amanda produce such verbose output that they are individually controlled by debug_* directives in amanda.conf(5). In general, this is handled with a macro such as

#define auth_debug(i, ...) do {         \
        if ((i) <= debug_auth) {        \
            dbprintf(__VA_ARGS__);      \
        }                               \
} while (0)

where conffile.c has been modified to set the relevant debug variable (debug_auth in this case).

Debugging Other Applications

Amanda often runs other applications (dumpers, security utilities, and so on), and it is often necessary to redirect the stderr of those applications to the debug log. 'dbfd' returns the file descriptor for the debug file, which can be manipulated as necesary (e.g., with dup2) to connect it to an external application.