- the debugging library <EM>libncurses</EM><STRONG>_</STRONG><EM>g.a</EM>, but may be compiled
- into any model (shared, static, profile) by defining the
- symbol <STRONG>TRACE</STRONG>. Additionally, some functions are only
- available with the wide-character configuration of the li-
- braries.
-
- 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
+ the debugging library e.g., <EM>libncurses</EM><STRONG>_</STRONG><EM>g.a</EM>, but may be
+ compiled into any model (shared, static, profile) by
+ defining the symbol <STRONG>TRACE</STRONG>. Additionally, some functions
+ 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>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.
+
+ Calling <STRONG>trace</STRONG> with a nonzero parameter creates the file
+ <STRONG>trace</STRONG> in the current directory for output. If the file
+ already exists, no tracing is done.
+
+ The other functions either return a pointer to a string-
+ area (allocated 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.
+
+
+</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 in-
+ clude:
+
+ <STRONG>TRACE_DISABLE</STRONG>
+ turn off tracing by passing a zero parameter.
+
+ The library flushes the output file, but retains an
+ open file-descriptor to the trace file so that it can
+ resume tracing later if a nonzero parameter is passed
+ to the <STRONG>trace</STRONG> function.
+
+ <STRONG>TRACE_TIMES</STRONG>