<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2008 (1.71)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Developing Bacula</TITLE>
<META NAME="description" CONTENT="Developing Bacula">
<META NAME="keywords" CONTENT="developers">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="developers.css">
<LINK REL="previous" HREF="Patches_Released_Versions.html">
<LINK REL="up" HREF="Bacula_Developer_Notes.html">
<LINK REL="next" HREF="Bacula_Git_Usage.html">
</HEAD>
<BODY >
<!--Navigation Panel-->
<A NAME="tex2html505"
HREF="Bacula_Git_Usage.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html499"
HREF="Bacula_Developer_Notes.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html495"
HREF="Patches_Released_Versions.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html501"
HREF="Contents.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html503"
HREF="GNU_Free_Documentation_Lice.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html506"
HREF="Bacula_Git_Usage.html">Bacula Git Usage</A>
<B> Up:</B> <A NAME="tex2html500"
HREF="Bacula_Developer_Notes.html">Bacula Developer Notes</A>
<B> Previous:</B> <A NAME="tex2html496"
HREF="Patches_Released_Versions.html">Patches for Released Versions</A>
<B> <A NAME="tex2html502"
HREF="Contents.html">Contents</A></B>
<B> <A NAME="tex2html504"
HREF="GNU_Free_Documentation_Lice.html">Index</A></B>
<BR>
<BR>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html507"
HREF="Developing_Bacula.html#SECTION00241000000000000000">Debugging</A>
<LI><A NAME="tex2html508"
HREF="Developing_Bacula.html#SECTION00242000000000000000">Using a Debugger</A>
<LI><A NAME="tex2html509"
HREF="Developing_Bacula.html#SECTION00243000000000000000">Memory Leaks</A>
<LI><A NAME="tex2html510"
HREF="Developing_Bacula.html#SECTION00244000000000000000">Special Files</A>
<LI><A NAME="tex2html511"
HREF="Developing_Bacula.html#SECTION00245000000000000000">When Implementing Incomplete Code</A>
<LI><A NAME="tex2html512"
HREF="Developing_Bacula.html#SECTION00246000000000000000">Bacula Source File Structure</A>
<LI><A NAME="tex2html513"
HREF="Developing_Bacula.html#SECTION00247000000000000000">Header Files</A>
<LI><A NAME="tex2html514"
HREF="Developing_Bacula.html#SECTION00248000000000000000">Programming Standards</A>
<LI><A NAME="tex2html515"
HREF="Developing_Bacula.html#SECTION00249000000000000000">Do Not Use</A>
<LI><A NAME="tex2html516"
HREF="Developing_Bacula.html#SECTION002410000000000000000">Avoid if Possible</A>
<LI><A NAME="tex2html517"
HREF="Developing_Bacula.html#SECTION002411000000000000000">Do Use Whenever Possible</A>
<LI><A NAME="tex2html518"
HREF="Developing_Bacula.html#SECTION002412000000000000000">Indenting Standards</A>
<LI><A NAME="tex2html519"
HREF="Developing_Bacula.html#SECTION002413000000000000000">Tabbing</A>
<LI><A NAME="tex2html520"
HREF="Developing_Bacula.html#SECTION002414000000000000000">Don'ts</A>
<LI><A NAME="tex2html521"
HREF="Developing_Bacula.html#SECTION002415000000000000000">Message Classes</A>
<LI><A NAME="tex2html522"
HREF="Developing_Bacula.html#SECTION002416000000000000000">Debug Messages</A>
<LI><A NAME="tex2html523"
HREF="Developing_Bacula.html#SECTION002417000000000000000">Error Messages</A>
<LI><A NAME="tex2html524"
HREF="Developing_Bacula.html#SECTION002418000000000000000">Job Messages</A>
<LI><A NAME="tex2html525"
HREF="Developing_Bacula.html#SECTION002419000000000000000">Queued Job Messages</A>
<LI><A NAME="tex2html526"
HREF="Developing_Bacula.html#SECTION002420000000000000000">Memory Messages</A>
<LI><A NAME="tex2html527"
HREF="Developing_Bacula.html#SECTION002421000000000000000">Bugs Database</A>
</UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION00240000000000000000"></A>
<A NAME="173"></A>
<A NAME="174"></A>
<BR>
Developing Bacula
</H1>
<P>
Typically the simplest way to develop Bacula is to open one xterm window
pointing to the source directory you wish to update; a second xterm window at
the top source directory level, and a third xterm window at the bacula
directory top/src/bacula. After making source changes in one of the
directories, in the top source directory xterm, build the source, and start
the daemons by entering:
<P>
make and
<P>
./startit then in the enter:
<P>
./console or
<P>
./gnome-console to start the Console program. Enter any commands for testing.
For example: run kernsverify full.
<P>
Note, the instructions here to use <B>./startit</B> are different from using a
production system where the administrator starts Bacula by entering <B>./bacula start</B>. This difference allows a development version of <B>Bacula</B>
to be run on a computer at the same time that a production system is running.
The <B>./startit</B> strip starts <B>Bacula</B> using a different set of
configuration files, and thus permits avoiding conflicts with any production
system.
<P>
To make additional source changes, exit from the Console program, and in the
top source directory, stop the daemons by entering:
<P>
./stopit then repeat the process.
<P>
<H2><A NAME="SECTION00241000000000000000"></A>
<A NAME="186"></A>
<BR>
Debugging
</H2>
<P>
Probably the first thing to do is to turn on debug output.
<P>
A good place to start is with a debug level of 20 as in <B>./startit -d20</B>.
The startit command starts all the daemons with the same debug level.
Alternatively, you can start the appropriate daemon with the debug level you
want. If you really need more info, a debug level of 60 is not bad, and for
just about everything a level of 200.
<P>
<H2><A NAME="SECTION00242000000000000000"></A>
<A NAME="192"></A>
<A NAME="193"></A>
<BR>
Using a Debugger
</H2>
<P>
If you have a serious problem such as a segmentation fault, it can usually be
found quickly using a good multiple thread debugger such as <B>gdb</B>. For
example, suppose you get a segmentation violation in <B>bacula-dir</B>. You
might use the following to find the problem:
<P>
start the Storage and File daemons
cd dird
gdb ./bacula-dir
run -f -s -c ./dird.conf
it dies with a segmentation fault
where
The <B>-f</B> option is specified on the <B>run</B> command to inhibit <B>dird</B> from going into the background. You may also want to add the <B>-s</B>
option to the run command to disable signals which can potentially interfere
with the debugging.
<P>
As an alternative to using the debugger, each <B>Bacula</B> daemon has a built
in back trace feature when a serious error is encountered. It calls the
debugger on itself, produces a back trace, and emails the report to the
developer. For more details on this, please see the chapter in the main Bacula
manual entitled ``What To Do When Bacula Crashes (Kaboom)''.
<P>
<H2><A NAME="SECTION00243000000000000000"></A>
<A NAME="209"></A>
<A NAME="210"></A>
<BR>
Memory Leaks
</H2>
<P>
Because Bacula runs routinely and unattended on client and server machines, it
may run for a long time. As a consequence, from the very beginning, Bacula
uses SmartAlloc to ensure that there are no memory leaks. To make detection of
memory leaks effective, all Bacula code that dynamically allocates memory MUST
have a way to release it. In general when the memory is no longer needed, it
should be immediately released, but in some cases, the memory will be held
during the entire time that Bacula is executing. In that case, there MUST be a
routine that can be called at termination time that releases the memory. In
this way, we will be able to detect memory leaks. Be sure to immediately
correct any and all memory leaks that are printed at the termination of the
daemons.
<P>
<H2><A NAME="SECTION00244000000000000000"></A>
<A NAME="215"></A>
<A NAME="216"></A>
<BR>
Special Files
</H2>
<P>
Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus
any files with these names are subject to being rudely deleted at any time.
<P>
<H2><A NAME="SECTION00245000000000000000"></A>
<A NAME="221"></A>
<A NAME="222"></A>
<BR>
When Implementing Incomplete Code
</H2>
<P>
Please identify all incomplete code with a comment that contains
<P>
<PRE>
***FIXME***
</PRE>
<P>
where there are three asterisks (*) before and after the word
FIXME (in capitals) and no intervening spaces. This is important as it allows
new programmers to easily recognize where things are partially implemented.
<P>
<H2><A NAME="SECTION00246000000000000000"></A>
<A NAME="229"></A>
<A NAME="230"></A>
<BR>
Bacula Source File Structure
</H2>
<P>
The distribution generally comes as a tar file of the form <B>bacula.x.y.z.tar.gz</B> where x, y, and z are the version, release, and update
numbers respectively.
<P>
Once you detar this file, you will have a directory structure as follows:
<P>
<PRE>
|
Tar file:
|- depkgs
|- mtx (autochanger control program + tape drive info)
|- sqlite (SQLite database program)
Tar file:
|- depkgs-win32
|- pthreads (Native win32 pthreads library -- dll)
|- zlib (Native win32 zlib library)
|- wx (wxWidgets source code)
Project bacula:
|- bacula (main source directory containing configuration
| and installation files)
|- autoconf (automatic configuration files, not normally used
| by users)
|- intl (programs used to translate)
|- platforms (OS specific installation files)
|- redhat (Red Hat installation)
|- solaris (Sun installation)
|- freebsd (FreeBSD installation)
|- irix (Irix installation -- not tested)
|- unknown (Default if system not identified)
|- po (translations of source strings)
|- src (source directory; contains global header files)
|- cats (SQL catalog database interface directory)
|- console (bacula user agent directory)
|- dird (Director daemon)
|- filed (Unix File daemon)
|- win32 (Win32 files to make bacula-fd be a service)
|- findlib (Unix file find library for File daemon)
|- gnome-console (GNOME version of console program)
|- lib (General Bacula library)
|- stored (Storage daemon)
|- tconsole (Tcl/tk console program -- not yet working)
|- testprogs (test programs -- normally only in Kern's tree)
|- tools (Various tool programs)
|- win32 (Native Win32 File daemon)
|- baculafd (Visual Studio project file)
|- compat (compatibility interface library)
|- filed (links to src/filed)
|- findlib (links to src/findlib)
|- lib (links to src/lib)
|- console (beginning of native console program)
|- wx-console (wxWidget console Win32 specific parts)
|- wx-console (wxWidgets console main source program)
Project regress:
|- regress (Regression scripts)
|- bin (temporary directory to hold Bacula installed binaries)
|- build (temporary directory to hold Bacula source)
|- scripts (scripts and .conf files)
|- tests (test scripts)
|- tmp (temporary directory for temp files)
|- working (temporary working directory for Bacula daemons)
Project docs:
|- docs (documentation directory)
|- developers (Developer's guide)
|- home-page (Bacula's home page source)
|- manual (html document directory)
|- manual-fr (French translation)
|- manual-de (German translation)
|- techlogs (Technical development notes);
Project rescue:
|- rescue (Bacula rescue CDROM)
|- linux (Linux rescue CDROM)
|- cdrom (Linux rescue CDROM code)
...
|- solaris (Solaris rescue -- incomplete)
|- freebsd (FreeBSD rescue -- incomplete)
Project gui:
|- gui (Bacula GUI projects)
|- bacula-web (Bacula web php management code)
|- bimagemgr (Web application for burning CDROMs)
</PRE>
<P>
<H2><A NAME="SECTION00247000000000000000"></A>
<A NAME="238"></A>
<A NAME="239"></A>
<BR>
Header Files
</H2>
<P>
Please carefully follow the scheme defined below as it permits in general only
two header file includes per C file, and thus vastly simplifies programming.
With a large complex project like Bacula, it isn't always easy to ensure that
the right headers are invoked in the right order (there are a few kludges to
make this happen - i.e. in a few include files because of the chicken and egg
problem, certain references to typedefs had to be replaced with <B>void</B> ).
<P>
Every file should include <B>bacula.h</B>. It pulls in just about everything,
with very few exceptions. If you have system dependent ifdefing, please do it
in <B>baconfig.h</B>. The version number and date are kept in <B>version.h</B>.
<P>
Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored,
...) contains a single directory dependent include file generally the name of
the directory, which should be included just after the include of <B>bacula.h</B>. This file (for example, for the dird directory, it is <B>dird.h</B>)
contains either definitions of things generally needed in this directory, or
it includes the appropriate header files. It always includes <B>protos.h</B>.
See below.
<P>
Each subdirectory contains a header file named <B>protos.h</B>, which contains
the prototypes for subroutines exported by files in that directory. <B>protos.h</B> is always included by the main directory dependent include file.
<P>
<H2><A NAME="SECTION00248000000000000000"></A>
<A NAME="253"></A>
<A NAME="254"></A>
<BR>
Programming Standards
</H2>
<P>
For the most part, all code should be written in C unless there is a burning
reason to use C++, and then only the simplest C++ constructs will be used.
Note, Bacula is slowly evolving to use more and more C++.
<P>
Code should have some documentation - not a lot, but enough so that I can
understand it. Look at the current code, and you will see that I document more
than most, but am definitely not a fanatic.
<P>
We prefer simple linear code where possible. Gotos are strongly discouraged
except for handling an error to either bail out or to retry some code, and
such use of gotos can vastly simplify the program.
<P>
Remember this is a C program that is migrating to a <B>tiny</B> subset of C++,
so be conservative in your use of C++ features.
<P>
<H2><A NAME="SECTION00249000000000000000"></A>
<A NAME="260"></A>
<A NAME="261"></A>
<BR>
Do Not Use
</H2>
<P>
<UL>
<LI>STL - it is totally incomprehensible.
</LI>
</UL>
<P>
<H2><A NAME="SECTION002410000000000000000"></A>
<A NAME="268"></A>
<A NAME="269"></A>
<BR>
Avoid if Possible
</H2>
<P>
<UL>
<LI>Using <B>void *</B> because this generally means that one must
using casting, and in C++ casting is rather ugly. It is OK to use
void * to pass structure address where the structure is not known
to the routines accepting the packet (typically callback routines).
However, declaring "void *buf" is a bad idea. Please use the
correct types whenever possible.
<P>
</LI>
<LI>Using undefined storage specifications such as (short, int, long,
long long, size_t ...). The problem with all these is that the number of bytes
they allocate depends on the compiler and the system. Instead use
Bacula's types (int8_t, uint8_t, int32_t, uint32_t, int64_t, and
uint64_t). This guarantees that the variables are given exactly the
size you want. Please try at all possible to avoid using size_t ssize_t
and the such. They are very system dependent. However, some system
routines may need them, so their use is often unavoidable.
<P>
</LI>
<LI>Returning a malloc'ed buffer from a subroutine - someone will forget
to release it.
<P>
</LI>
<LI>Heap allocation (malloc) unless needed - it is expensive. Use
POOL_MEM instead.
<P>
</LI>
<LI>Templates - they can create portability problems.
<P>
</LI>
<LI>Fancy or tricky C or C++ code, unless you give a good explanation of
why you used it.
<P>
</LI>
<LI>Too much inheritance - it can complicate the code, and make reading it
difficult (unless you are in love with colons)
<P>
</LI>
</UL>
<P>
<H2><A NAME="SECTION002411000000000000000"></A>
<A NAME="277"></A>
<A NAME="278"></A>
<BR>
Do Use Whenever Possible
</H2>
<P>
<UL>
<LI>Locking and unlocking within a single subroutine.
<P>
</LI>
<LI>A single point of exit from all subroutines. A goto is
perfectly OK to use to get out early, but only to a label
named bail_out, and possibly an ok_out. See current code
examples.
<P>
</LI>
<LI>Malloc and free within a single subroutine.
<P>
</LI>
<LI>Comments and global explanations on what your code or algorithm does.
<P>
</LI>
</UL>
<P>
<H2><A NAME="SECTION002412000000000000000"></A>
<A NAME="285"></A>
<A NAME="286"></A>
<BR>
Indenting Standards
</H2>
<P>
We find it very hard to read code indented 8 columns at a time.
Even 4 at a time uses a lot of space, so we have adopted indenting
3 spaces at every level. Note, indention is the visual appearance of the
source on the page, while tabbing is replacing a series of up to 8 spaces from
a tab character.
<P>
The closest set of parameters for the Linux <B>indent</B> program that will
produce reasonably indented code are:
<P>
<PRE>
-nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0
-cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs
-nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda
</PRE>
<P>
You can put the above in your .indent.pro file, and then just invoke indent on
your file. However, be warned. This does not produce perfect indenting, and it
will mess up C++ class statements pretty badly.
<P>
Braces are required in all if statements (missing in some very old code). To
avoid generating too many lines, the first brace appears on the first line
(e.g. of an if), and the closing brace is on a line by itself. E.g.
<P>
<PRE>
if (abc) {
some_code;
}
</PRE>
<P>
Just follow the convention in the code. For example we I prefer non-indented cases.
<P>
<PRE>
switch (code) {
case 'A':
do something
break;
case 'B':
again();
break;
default:
break;
}
</PRE>
<P>
Avoid using // style comments except for temporary code or turning off debug
code. Standard C comments are preferred (this also keeps the code closer to
C).
<P>
Attempt to keep all lines less than 85 characters long so that the whole line
of code is readable at one time. This is not a rigid requirement.
<P>
Always put a brief description at the top of any new file created describing
what it does and including your name and the date it was first written. Please
don't forget any Copyrights and acknowledgments if it isn't 100% your code.
Also, include the Bacula copyright notice that is in <B>src/c</B>.
<P>
In general you should have two includes at the top of the an include for the
particular directory the code is in, for includes are needed, but this should
be rare.
<P>
In general (except for self-contained packages), prototypes should all be put
in <B>protos.h</B> in each directory.
<P>
Always put space around assignment and comparison operators.
<P>
<PRE>
a = 1;
if (b >= 2) {
cleanup();
}
</PRE>
<P>
but your can compress things in a <B>for</B> statement:
<P>
<PRE>
for (i=0; i < del.num_ids; i++) {
...
</PRE>
<P>
Don't overuse the inline if (?:). A full <B>if</B> is preferred, except in a
print statement, e.g.:
<P>
<PRE>
if (ua->verbose \&& del.num_del != 0) {
bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del,
del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName);
}
</PRE>
<P>
Leave a certain amount of debug code (Dmsg) in code you submit, so that future
problems can be identified. This is particularly true for complicated code
likely to break. However, try to keep the debug code to a minimum to avoid
bloating the program and above all to keep the code readable.
<P>
Please keep the same style in all new code you develop. If you include code
previously written, you have the option of leaving it with the old indenting
or re-indenting it. If the old code is indented with 8 spaces, then please
re-indent it to Bacula standards.
<P>
If you are using <B>vim</B>, simply set your tabstop to 8 and your shiftwidth
to 3.
<P>
<H2><A NAME="SECTION002413000000000000000"></A>
<A NAME="309"></A>
<BR>
Tabbing
</H2>
<P>
Tabbing (inserting the tab character in place of spaces) is as normal on all
Unix systems - a tab is converted space up to the next column multiple of 8.
My editor converts strings of spaces to tabs automatically - this results in
significant compression of the files. Thus, you can remove tabs by replacing
them with spaces if you wish. Please don't confuse tabbing (use of tab
characters) with indenting (visual alignment of the code).
<P>
<H2><A NAME="SECTION002414000000000000000"></A>
<A NAME="314"></A>
<BR>
Don'ts
</H2>
<P>
Please don't use:
<P>
<PRE>
strcpy()
strcat()
strncpy()
strncat();
sprintf()
snprintf()
</PRE>
<P>
They are system dependent and un-safe. These should be replaced by the Bacula
safe equivalents:
<P>
<PRE>
char *bstrncpy(char *dest, char *source, int dest_size);
char *bstrncat(char *dest, char *source, int dest_size);
int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...);
int bvsnprintf(char *str, int32_t size, const char *format, va_list ap);
</PRE>
<P>
See src/lib/bsys.c for more details on these routines.
<P>
Don't use the <B>%lld</B> or the <B>%q</B> printf format editing types to edit
64 bit integers - they are not portable. Instead, use <B>%s</B> with <B>edit_uint64()</B>. For example:
<P>
<PRE>
char buf[100];
uint64_t num = something;
char ed1[50];
bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1));
</PRE>
<P>
Note: <B>%lld</B> is now permitted in Bacula code - we have our
own printf routines which handle it correctly. The edit_uint64() subroutine
can still be used if you wish, but over time, most of that old style will
be removed.
<P>
The edit buffer <B>ed1</B> must be at least 27 bytes long to avoid overflow.
See src/lib/edit.c for more details. If you look at the code, don't start
screaming that I use <B>lld</B>. I actually use subtle trick taught to me by
John Walker. The <B>lld</B> that appears in the editing routine is actually
<B>#define</B> to a what is needed on your OS (usually ``lld'' or ``q'') and
is defined in autoconf/configure.in for each OS. C string concatenation causes
the appropriate string to be concatenated to the ``%''.
<P>
Also please don't use the STL or Templates or any complicated C++ code.
<P>
<H2><A NAME="SECTION002415000000000000000"></A>
<A NAME="334"></A>
<A NAME="335"></A>
<BR>
Message Classes
</H2>
<P>
Currently, there are five classes of messages: Debug, Error, Job, Memory,
and Queued.
<P>
<H2><A NAME="SECTION002416000000000000000"></A>
<A NAME="340"></A>
<A NAME="341"></A>
<BR>
Debug Messages
</H2>
<P>
Debug messages are designed to be turned on at a specified debug level and are
always sent to STDOUT. There are designed to only be used in the development
debug process. They are coded as:
<P>
DmsgN(level, message, arg1, ...) where the N is a number indicating how many
arguments are to be substituted into the message (i.e. it is a count of the
number arguments you have in your message - generally the number of percent
signs (%)). <B>level</B> is the debug level at which you wish the message to
be printed. message is the debug message to be printed, and arg1, ... are the
arguments to be substituted. Since not all compilers support #defines with
varargs, you must explicitly specify how many arguments you have.
<P>
When the debug message is printed, it will automatically be prefixed by the
name of the daemon which is running, the filename where the Dmsg is, and the
line number within the file.
<P>
Some actual examples are:
<P>
Dmsg2(20, ``MD5len=%d MD5=%s\n'', strlen(buf), buf);
<P>
Dmsg1(9, ``Created client %s record\n'', client->hdr.name);
<P>
<H2><A NAME="SECTION002417000000000000000"></A>
<A NAME="349"></A>
<A NAME="350"></A>
<BR>
Error Messages
</H2>
<P>
Error messages are messages that are related to the daemon as a whole rather
than a particular job. For example, an out of memory condition my generate an
error message. They should be very rarely needed. In general, you should be
using Job and Job Queued messages (Jmsg and Qmsg). They are coded as:
<P>
EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must
explicitly code the of arguments to be substituted in the message. error-code
indicates the severity or class of error, and it may be one of the following:
<P>
<TABLE CELLPADDING=3>
<TR><TD ALIGN="LEFT"><B>M_ABORT</B></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=216>Causes the daemon to immediately abort. This should be
used only in extreme cases. It attempts to produce a traceback.</TD>
</TR>
<TR><TD ALIGN="LEFT"><B>M_ERROR_TERM</B></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=216>Causes the daemon to immediately terminate. This
should be used only in extreme cases. It does not produce a traceback.</TD>
</TR>
<TR><TD ALIGN="LEFT"><B>M_FATAL</B></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=216>Causes the daemon to terminate the current job, but the
daemon keeps running</TD>
</TR>
<TR><TD ALIGN="LEFT"><B>M_ERROR</B></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=216>Reports the error. The daemon and the job continue
running</TD>
</TR>
<TR><TD ALIGN="LEFT"><B>M_WARNING</B></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=216>Reports an warning message. The daemon and the job
continue running</TD>
</TR>
<TR><TD ALIGN="LEFT"><B>M_INFO</B></TD>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=216>Reports an informational message.
<P></TD>
</TR>
</TABLE>
<P>
There are other error message classes, but they are in a state of being
redesigned or deprecated, so please do not use them. Some actual examples are:
<P>
Emsg1(M_ABORT, 0, ``Cannot create message thread: %s\n'',
strerror(status));
<P>
Emsg3(M_WARNING, 0, ``Connect to File daemon %s at %s:%d failed. Retrying
...\n'', client-hdr.name, client-address,
client-port);
<P>
Emsg3(M_FATAL, 0, ``bdirdfiled: bad response from Filed to %s command:
%d %s\n'', cmd, n, strerror(errno));
<P>
<H2><A NAME="SECTION002418000000000000000"></A>
<A NAME="380"></A>
<A NAME="381"></A>
<BR>
Job Messages
</H2>
<P>
Job messages are messages that pertain to a particular job such as a file that
could not be saved, or the number of files and bytes that were saved. They
Are coded as:
<PRE>
Jmsg(jcr, M\_FATAL, 0, "Text of message");
</PRE>
A Jmsg with M_FATAL will fail the job. The Jmsg() takes varargs so can
have any number of arguments for substituted in a printf like format.
Output from the Jmsg() will go to the Job report.
<br>
If the Jmsg is followed with a number such as Jmsg1(...), the number
indicates the number of arguments to be substituted (varargs is not
standard for #defines), and what is more important is that the file and
line number will be prefixed to the message. This permits a sort of debug
from user's output.
<P>
<H2><A NAME="SECTION002419000000000000000"></A>
<A NAME="388"></A>
<A NAME="389"></A>
<BR>
Queued Job Messages
</H2>
Queued Job messages are similar to Jmsg()s except that the message is
Queued rather than immediately dispatched. This is necessary within the
network subroutines and in the message editing routines. This is to prevent
recursive loops, and to ensure that messages can be delivered even in the
event of a network error.
<P>
<H2><A NAME="SECTION002420000000000000000"></A>
<A NAME="394"></A>
<A NAME="395"></A>
<BR>
Memory Messages
</H2>
<P>
Memory messages are messages that are edited into a memory buffer. Generally
they are used in low level routines such as the low level device file dev.c in
the Storage daemon or in the low level Catalog routines. These routines do not
generally have access to the Job Control Record and so they return error
essages reformatted in a memory buffer. Mmsg() is the way to do this.
<P>
<H2><A NAME="SECTION002421000000000000000"></A>
<A NAME="400"></A>
<A NAME="401"></A>
<BR>
Bugs Database
</H2>
We have a bugs database which is at:
http://bugs.bacula.orghttp://bugs.bacula.org, and as
a developer you will need to respond to bugs, perhaps bugs in general
if you have time, otherwise just bugs that correspond to code that
you wrote.
<P>
If you need to answer bugs, please be sure to ask the Project Manager
(currently Kern) to give you Developer access to the bugs database. This
allows you to modify statuses and close bugs.
<P>
The first thing is if you want to take over a bug, rather than just make a
note, you should assign the bug to yourself. This helps other developers
know that you are the principal person to deal with the bug. You can do so
by going into the bug and clicking on the <B>Update Issue</B> button. Then
you simply go to the <B>Assigned To</B> box and select your name from the
drop down box. To actually update it you must click on the <B>Update
Information</B> button a bit further down on the screen, but if you have other
things to do such as add a Note, you might wait before clicking on the <B>Update Information</B> button.
<P>
Generally, we set the <B>Status</B> field to either acknowledged, confirmed,
or feedback when we first start working on the bug. Feedback is set when
we expect that the user should give us more information.
<P>
Normally, once you are reasonably sure that the bug is fixed, and a patch
is made and attached to the bug report, and/or in the SVN, you can close
the bug. If you want the user to test the patch, then leave the bug open,
otherwise close it and set <B>Resolution</B> to <B>Fixed</B>. We generally
close bug reports rather quickly, even without confirmation, especially if
we have run tests and can see that for us the problem is fixed. However,
in doing so, it avoids misunderstandings if you leave a note while you are
closing the bug that says something to the following effect:
We are closing this bug because ... If for some reason, it does not fix
your problem, please feel free to reopen it, or to open a new bug report
describing the problem".
<P>
We do not recommend that you attempt to edit any of the bug notes that have
been submitted, nor to delete them or make them private. In fact, if
someone accidentally makes a bug note private, you should ask the reason
and if at all possible (with his agreement) make the bug note public.
<P>
If the user has not properly filled in most of the important fields
(platorm, OS, Product Version, ...) please do not hesitate to politely ask
him. Also, if the bug report is a request for a new feature, please
politely send the user to the Feature Request menu item on www.bacula.org.
The same applies to a support request (we answer only bugs), you might give
the user a tip, but please politely refer him to the manual and the
Getting Support page of www.bacula.org.
<HR>
<!--Navigation Panel-->
<A NAME="tex2html505"
HREF="Bacula_Git_Usage.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html499"
HREF="Bacula_Developer_Notes.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html495"
HREF="Patches_Released_Versions.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html501"
HREF="Contents.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html503"
HREF="GNU_Free_Documentation_Lice.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html506"
HREF="Bacula_Git_Usage.html">Bacula Git Usage</A>
<B> Up:</B> <A NAME="tex2html500"
HREF="Bacula_Developer_Notes.html">Bacula Developer Notes</A>
<B> Previous:</B> <A NAME="tex2html496"
HREF="Patches_Released_Versions.html">Patches for Released Versions</A>
<B> <A NAME="tex2html502"
HREF="Contents.html">Contents</A></B>
<B> <A NAME="tex2html504"
HREF="GNU_Free_Documentation_Lice.html">Index</A></B>
<!--End of Navigation Panel-->
<ADDRESS>
2012-01-24
</ADDRESS>
</BODY>
</HTML>
