aboutsummaryrefslogtreecommitdiff
path: root/docs/doxygen/nel/log_howto.html
blob: 95bf251b8ca830df6063f2950347f7b852170915 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
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>