aboutsummaryrefslogtreecommitdiff
path: root/docs/doxygen/nel/log_howto.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/doxygen/nel/log_howto.html')
-rw-r--r--docs/doxygen/nel/log_howto.html141
1 files changed, 141 insertions, 0 deletions
diff --git a/docs/doxygen/nel/log_howto.html b/docs/doxygen/nel/log_howto.html
new file mode 100644
index 00000000..95bf251b
--- /dev/null
+++ b/docs/doxygen/nel/log_howto.html
@@ -0,0 +1,141 @@
+<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<HTML>
+<HEAD>
+ <TITLE>nevrax.org : docs</TITLE>
+ <LINK REL=stylesheet TYPE="text/css" HREF="http://www.nevrax.org/inc/css/nevrax.css">
+ <link href="doxygen.css" rel="stylesheet" type="text/css">
+</HEAD>
+<BODY MARGINHEIGHT="0" MARGINWIDTH="0">
+
+<!-- uplinks -->
+<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0>
+ <TR>
+ <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
+ <TD WIDTH=140 BGCOLOR=#dddddd><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="16" BORDER=0 ALT=""></TD>
+ <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
+ <TD><IMG width=6 height=14 SRC="http://www.nevrax.org/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle>&nbsp;<A CLASS=uplinks HREF=http://www.nevrax.org><b>Home</B></FONT></A>&nbsp;&nbsp;&nbsp;</TD>
+ <TD><IMG width=6 height=14 SRC="http://www.nevrax.org/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle>&nbsp;<A CLASS=uplinks HREF=http://www.nevrax.com><b>nevrax.com</B></FONT></A>&nbsp;&nbsp;&nbsp;</TD>
+ </TR>
+</TABLE>
+
+<!-- banner Nevrax -->
+<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0 WIDTH=100%>
+ <TR><TD BGCOLOR="#000000" BACKGROUND="http://www.nevrax.org/inc/img/black_banner.jpg"><A HREF="http://www.nevrax.org"><IMG SRC="http://www.nevrax.org/inc/img/nevrax.gif" WIDTH="170" HEIGHT="45" BORDER=0 ALT="Nevrax" ></A></TD></TR>
+</TABLE>
+
+<!-- main table -->
+<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0 height=100%>
+ <TR>
+ <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="10" BORDER=0 ALT=""></TD>
+ <TD WIDTH=140 BGCOLOR=#dddddd VALIGN=TOP ALIGN=middle><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">
+
+ <!------ Begin Box ------>
+ <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 BGCOLOR=black><TR><TD><TABLE border=0 cellspacing=2 cellpadding=0 width=120><tr><TD ALIGN=middle bgcolor=black>
+ <FONT COLOR=white FACE="sans-serif"><B>Nevrax.org</B></FONT></TD></TR><tr><td colspan=2 bgcolor=#FFFFFF>
+ <TABLE cellspacing=0 cellpadding=1 border=0>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/news/" TITLE="Rubrique news"><img width=13 height=15 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-news.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/news/" TITLE="News">News</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/mail/" TITLE="Rubrique mail"><img width=15 height=11 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-mail.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/mail/" TITLE="Mailing list archive">Mailing-list</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/docs/" TITLE="Rubrique docs"><img width=14 height=16 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-docs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/docs/" TITLE="Documentation">Documentation</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/cvs/" TITLE="Rubrique cvs"><img width=13 height=17 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-cvs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/cvs/" TITLE="CVS Web">CVS</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/bugs/" TITLE="Rubrique bugs"><img width=20 height=16 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-bugs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/bugs/" TITLE="Bugtracking">Bugs</a></td></tr>
+ <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/GPL.php3" TITLE="Rubrique license"><img width=18 height=12 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-gpl.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/GPL.php3" TITLE="License">License</a></td></tr>
+ </TABLE>
+ </TD></TR></TABLE></TD></TR></TABLE>
+ <!------ End Box ------>
+
+ </TD>
+ <TD WIDTH=15><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
+ <TD ALIGN=left valign=top><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">
+
+<!-- title -->
+<TABLE background="http://www.nevrax.org/inc/img/redline.gif" CELLSPACING=0 CELLPADDING=0 BORDER=0 width=100%><tr><td>
+<A HREF="http://www.nevrax.org/docs/"><img src="http://www.nevrax.org/inc/img/t_docs.gif" ALT="Docs" HEIGHT=20 BORDER=0></A>
+</td><td><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="1" HEIGHT="1" BORDER=0 ALT="">
+</td></tr></table>
+&nbsp;
+
+<!-- block -->
+<TABLE bgcolor="#dddddd" CELLSPACING=0 CELLPADDING=0 BORDER=0 width=100%><tr><td width=1% valign=middle><img width=6 height=14 hspace=2 vspace=2 src="http://www.nevrax.org/inc/img/reddots.gif"></TD>
+ <TD><B>Documentation</B></TD>
+ <TD ALIGN=RIGHT>&nbsp;</td>
+</tr></table>
+<!-- Generated by Doxygen 1.2.14 -->
+<center>
+<a class="qindex" href="index.html">Main Page</a> &nbsp; <a class="qindex" href="namespaces.html">Namespace List</a> &nbsp; <a class="qindex" href="hierarchy.html">Class Hierarchy</a> &nbsp; <a class="qindex" href="classes.html">Alphabetical List</a> &nbsp; <a class="qindex" href="annotated.html">Compound List</a> &nbsp; <a class="qindex" href="files.html">File List</a> &nbsp; <a class="qindex" href="namespacemembers.html">Namespace Members</a> &nbsp; <a class="qindex" href="functions.html">Compound Members</a> &nbsp; <a class="qindex" href="globals.html">File Members</a> &nbsp; <a class="qindex" href="pages.html">Related Pages</a> &nbsp; <a class="qindexRef" doxygen="_cgi:http://www.nevrax.org/cgi-bin/nel-search.cgi" href="http://www.nevrax.org/cgi-bin/nel-search.cgi">Search</a> &nbsp; </center>
+<hr><a name="log_howto"><h2>How to log information (for debugging purpose) ?</h2></a>
+ <dl compact><dt><b>
+Author: </b><dd>
+Olivier Cado </dl><dl compact><dt><b>
+Date: </b><dd>
+Updated May 4 2001</dl>This document explains how to log some information (into the screen, into a file or to a logging server), e.g. in order to debug your code.
+<p>
+<a name="basic_debug"><h2>Basic usage of the debugging system</h2></a>
+ The debugging sytem allows to log information at various levels. Include the header file "<a class="el" href="debug_8h.html">nel/misc/debug.h</a>".
+<p>
+The main functionalities are offered by the macros nldebug, nlinfo, nlwarning and also nlerror and nlassert, and by their variant forms (see <a class="el" href="debug_8h.html">debug.h</a>). They allow to display strings, with open arguments, using the "printf" syntax. In the default behaviour, the text passed to nldebug is displayed into stdout in NL_DEBUG mode, but not in NL_RELEASE. The logged texts are also written into a file called "log.log" in the working directory. These macros print the strings with an information header.
+<p>
+Example : <div class="fragment"><pre> sint32 age = -2;
+ <a class="code" href="debug_8h.html#a0">nldebug</a>( <font class="stringliteral">"Toto is %d years old"</font>, age );
+ <font class="keywordflow">if</font> ( age &lt; 0 )
+ {
+ <a class="code" href="debug_8h.html#a3">nlerror</a>( <font class="stringliteral">"Invalid age for toto : %d"</font>, age );
+
+ <font class="comment">// the program will not come here because nlerror throws an exception to exit</font>
+ }
+
+ STDOUT (logger thread_id <a class="code" href="cf__lexical_8cpp.html#a95">file</a> line: debug_string):
+ DBG 1234 myfile.cpp 10: Toto is -2 years old
+ ERR 1234 myfile.cpp 13: Invalid age for <a class="code" href="namespaceNLMISC.html#a294">toto</a> : -2
+ Abort
+
+ FILE OUTPUT (date time logger debug_string):
+ 01/04/11 18:24:50 DBG: Toto is -2 years old
+ 01/04/11 18:24:50 ERR: Invalid age for <a class="code" href="namespaceNLMISC.html#a294">toto</a> : -2
+</pre></div>
+<p>
+Because NeL allows to create multithreaded programs, these macros use mutual exclusions (mutex) to ensure no data is corrupted and the displayed text not interlaced.
+<p>
+<a name="adv_log"><h2>Advanced usage of the logging system</h2></a>
+
+<p>
+You may want to customize the logging system directly, for your own needs. Include "<a class="el" href="log_8h.html">nel/misc/log.h</a>".
+<p>
+<a name="init_log"><h3>Initialization</h3></a>
+ If your program is not a "service" in the NeL terms (i.e. if it is not built on <a class="el" href="classNLNET_1_1IService.html">NLNET::IService</a>), first call createDebug() to create the basic global loggers <em>ErrorLog</em>, <em>WarningLog</em>, <em>InfoLog</em>, <em>DebugLog</em> and <em>AssertLog</em> (the ones that are used by the nlerror, nlwarning, nlinfo, nldebug and nlassert macros).
+<p>
+Then, you can attach some displayers to the global loggers (<a class="el" href="classNLMISC_1_1CLog.html">NLMISC::CLog</a> objects).<ul>
+<li><a class="el" href="classNLMISC_1_1CStdDisplayer.html">NLMISC::CStdDisplayer</a> is for stdout (the console, the VC++ output window...). It is attached by default to all of the five logger objects mentionned above.<li><a class="el" href="classNLMISC_1_1CFileDisplayer.html">NLMISC::CFileDisplayer</a> is for a file.<li><a class="el" href="classNLMISC_1_1CMsgBoxDisplayer.html">NLMISC::CMsgBoxDisplayer</a> is for a message box.<li><a class="el" href="classNLNET_1_1CNetDisplayer.html">NLNET::CNetDisplayer</a> is for a logging server (see CLogService in the nelns documentation).<li>You can can create your own displayer, in order to print the logged text onto a new target (for example, see the class CChatDisplayer in Snowballs 0.2) or to customize the filter on the header.</ul>
+Example (we assume CNetDisplayer allows to log via the network): <div class="fragment"><pre> <a class="code" href="namespaceNLMISC.html#a247">createDebug</a>(); <font class="comment">// automatically done in a "service"</font>
+ <a class="code" href="classNLNET_1_1CNetDisplayer.html">NLNET::CNetDisplayer</a> *nd = <font class="keyword">new</font> CNetDisplayer(); <font class="comment">// the address of the Logging Server is automatically retrieved using the Naming Service</font>
+ <font class="keywordflow">if</font> ( nd-&gt;<a class="code" href="classNLNET_1_1CNetDisplayer.html#a3">connected</a>() ) <font class="comment">// this line is optional: here we don't want the displayer to attempt other connections if the first one failed</font>
+ {
+ NLMISC::DebugLog.addDisplayer( nd );
+ }
+</pre></div>
+<p>
+<a name="use_log"><h3>Logging information</h3></a>
+
+<p>
+How to log a string without repeating the header ? Use the methods of <a class="el" href="classNLMISC_1_1CLog.html">NLMISC::CLog</a>.
+<p>
+Example : <div class="fragment"><pre> NLMISC::DebugLog.displayNL ( <font class="stringliteral">"Dump of Values :"</font> );
+ <font class="keywordflow">for</font> ( <font class="keywordtype">int</font> j=0; j!=<a class="code" href="driver__opengl__extension__def_8h.html#a390">height</a>; ++j )
+ {
+ <font class="keywordflow">for</font> ( <font class="keywordtype">int</font> i=0; i!=<a class="code" href="driver__opengl__extension__def_8h.html#a389">width</a>; ++i )
+ {
+ NLMISC::DebugLog.displayRaw( <font class="stringliteral">"%d "</font>, Values[j][i] );
+ }
+ NLMISC::DebugLog.displayRawNL( <font class="stringliteral">": line %d"</font>, j );
+ }
+</pre></div>
+<p>
+
+
+<!-- footer -->
+<BR><FONT Size=+5>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; </FONT>
+</TD>
+<TD WIDTH=15><IMG SRC=http://www.nevrax.org/inc/img/pixel.gif WIDTH=15 HEIGHT=15 BORDER=0 ALT=""></TD>
+</TR>
+</TABLE>
+</BODY>
+</HTML>