-</PRE>
-<H2>DESCRIPTION</H2><PRE>
- The <STRONG>trace</STRONG> routines are used for debugging the ncurses
- libraries, as well as applications which use the ncurses
- libraries. These functions are normally available only
- with the debugging library <EM>libncurses</EM><STRONG>_</STRONG><EM>g.a</EM>, but may be com-
- piled into any model (shared, static, profile) by defining
- the symbol <STRONG>TRACE</STRONG>.
-
- The principal parts of this interface are the <STRONG>trace</STRONG> rou-
- tine which selectively enables different tracing features,
- and the <STRONG>_tracef</STRONG> routine which writes formatted data to the
- <EM>trace</EM> file.
-
- Calling <STRONG>trace</STRONG> with a nonzero parameter opens the file
- <STRONG>trace</STRONG> in the current directory for output. The parameter
- is formed by OR'ing values from the list of <STRONG>TRACE_</STRONG><EM>xxx</EM> def-
- initions in <STRONG><curses.h></STRONG>. These include:
-
- TRACE_DISABLE
- turn off tracing.
-
- TRACE_TIMES
+
+</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+ The <EM>curses</EM> <EM>trace</EM> routines are used for debugging the ncurses libraries,
+ as well as applications which use the ncurses libraries. Some limita-
+ tions apply:
+
+ <STRONG>o</STRONG> Aside from <STRONG>curses_trace</STRONG>, the other functions are normally available
+ only with the debugging library e.g., <EM>libncurses</EM><STRONG>_</STRONG><EM>g.a</EM>.
+
+ All of the trace functions may be compiled into any model (shared,
+ static, profile) by defining the symbol <STRONG>TRACE</STRONG>.
+
+ <STRONG>o</STRONG> Additionally, the functions which use <STRONG>cchar_t</STRONG> are only available
+ with the wide-character configuration of the libraries.
+
+
+</PRE><H3><a name="h3-Functions">Functions</a></H3><PRE>
+ The principal parts of this interface are
+
+ <STRONG>o</STRONG> <STRONG>curses_trace</STRONG>, which selectively enables different tracing features,
+ and
+
+ <STRONG>o</STRONG> <STRONG>_tracef</STRONG>, which writes formatted data to the <EM>trace</EM> file.
+
+ The other functions either return a pointer to a string-area (allo-
+ cated by the corresponding function), or return no value (such as
+ <STRONG>_tracedump</STRONG>, which implements the screen dump for <STRONG>TRACE_UPDATE</STRONG>).
+ The caller should not free these strings, since the allocation is
+ reused on successive calls. To work around the problem of a single
+ string-area per function, some use a buffer-number parameter,
+ telling the library to allocate additional string-areas.
+
+ The <STRONG>curses_trace</STRONG> function is always available, whether or not the other
+ trace functions are available:
+
+ <STRONG>o</STRONG> If tracing is available, calling <STRONG>curses_trace</STRONG> with a nonzero param-
+ eter updates the trace mask, and returns the previous trace mask.
+
+ When the trace mask is nonzero, ncurses creates the file "trace" in
+ the current directory for output. If the file already exists, no
+ tracing is done.
+
+ <STRONG>o</STRONG> If tracing is not available, <STRONG>curses_trace</STRONG> returns zero (0).
+
+
+</PRE><H3><a name="h3-Trace-Parameter">Trace Parameter</a></H3><PRE>
+ The trace parameter is formed by OR'ing values from the list of
+ <STRONG>TRACE_</STRONG><EM>xxx</EM> definitions in <STRONG><curses.h></STRONG>. These include:
+
+ <STRONG>TRACE_DISABLE</STRONG>
+ turn off tracing by passing a zero parameter.
+
+ The library flushes the output file, but retains an open file-de-
+ scriptor to the trace file so that it can resume tracing later if
+ a nonzero parameter is passed to the <STRONG>curses_trace</STRONG> function.
+
+ <STRONG>TRACE_TIMES</STRONG>