--- name: "trace" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/_nc_tracebits" --- # trace(3) curses debugging routines Part of [\_nc\_tracebits(3)](/_nc_tracebits/3.md). ## NAME **curses\_trace**, **trace**, **\_tracef**, **\_traceattr**, **\_traceattr2**, **\_tracecchar\_t**, **\_tracecchar\_t2**, **\_tracechar**, **\_tracechtype**, **\_tracechtype2**, **\_nc\_tracebits**, **\_tracedump**, **\_tracemouse** - *curses* debugging routines ## SYNOPSIS ``` #include ``` **unsigned curses\_trace(const unsigned** *trace-mask***);** **void \_tracef(const char \****format***, ...);** **char \*\_traceattr(attr\_t** *attr***);** **char \*\_traceattr2(int** *buffer***, chtype** *ch***);** **char \*\_tracecchar\_t(const cchar\_t \****string***);** **char \*\_tracecchar\_t2(int** *buffer***, const cchar\_t \****string***);** **char \*\_tracechar(int** *c***);** **char \*\_tracechtype(chtype** *ch***);** **char \*\_tracechtype2(int** *buffer***, chtype** *ch***);** **void \_tracedump(const char \****label***, WINDOW \****win***);** **char \*\_nc\_tracebits(void);** **char \*\_tracemouse(const MEVENT \****event***);** */\* deprecated \*/* **void trace(const unsigned int** *trace-mask***);** ## DESCRIPTION **The** *curses trace* **routines are used for debugging the** *ncurses* **libraries,** **as well as applications which use the** *ncurses* **libraries.** **Some limitations apply:** - • **Aside from curses\_trace,** **the other functions are normally available only with the debugging library** **e.g., libncurses\_g.a.** - **All of the trace functions may be compiled into any model (shared, static,** **profile) by defining the symbol TRACE.** - • **Additionally, the functions which use cchar\_t** **are only available with the wide-character configuration of the libraries.** ### Functions **The principal parts of this interface are** - • **curses\_trace, which selectively enables different tracing features, and** - • **\_tracef, which writes formatted data to the** *trace* **file.** - **The other functions either return a pointer to a string-area** **(allocated by the corresponding function), or return no value** **(such as \_tracedump,** **which implements the screen dump for TRACE\_UPDATE).** **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 curses\_trace function is always available,** **whether or not the other trace functions are available:** - • **If tracing is available,** **calling curses\_trace with a nonzero parameter** **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.** - • **If tracing is not available, curses\_trace returns zero (0).** ### Trace Parameter **The trace parameter is formed by logically “or”-ing** **values from the list of TRACE\_***xxx* definitions in **\**. These include: - **TRACE\_DISABLE** 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 **curses\_trace** function. - **TRACE\_TIMES** trace user and system times of updates. - **TRACE\_TPUTS** trace **tputs**(3X) calls. - **TRACE\_UPDATE** trace update actions, old & new screens. - **TRACE\_MOVE** trace cursor movement and scrolling. - **TRACE\_CHARPUT** trace all character outputs. - **TRACE\_ORDINARY** trace all update actions. The old and new screen contents are written to the trace file for each refresh. - **TRACE\_CALLS** trace all curses calls. The parameters for each call are traced, as well as return values. - **TRACE\_VIRTPUT** trace virtual character puts, i.e., calls to **addch**. - **TRACE\_IEVENT** trace low-level input processing, including timeouts. - **TRACE\_BITS** trace state of TTY control bits. - **TRACE\_ICALLS** trace internal/nested calls. - **TRACE\_CCALLS** trace per-character calls. - **TRACE\_DATABASE** trace read/write of terminfo/termcap data. - **TRACE\_ATTRS** trace changes to video attributes and colors. - **TRACE\_MAXIMUM** maximum trace level, enables all of the separate trace features. Some tracing features are enabled whenever the **curses\_trace** parameter is nonzero. Some features overlap. The specific names are used as a guideline. ### Command-line Utilities The command-line utilities such as [**tic**(1)](/tic/1.md) provide a verbose option which extends the set of messages written using the **curses\_trace** function. Both of these (**-v** and **curses\_trace**) use the same variable (**\_nc\_tracing**), which determines the messages which are written. Because the command-line utilities may call initialization functions such as **setupterm**, **tgetent** or **use\_extended\_names**, some of their debugging output may be directed to the *trace* file if the *NCURSES\_TRACE* environment variable is set: - • messages produced in the utility are written to the standard error. - • messages produced by the underlying library are written to *trace*. If *ncurses* is built without tracing, none of the latter are produced, and fewer diagnostics are provided by the command-line utilities. ## RETURN VALUE Routines which return a value are designed to be used as parameters to the **\_tracef** routine. ## ENVIRONMENT ### NCURSES\_TRACE A positive integral value stored in this variable causes the following functions to enable the tracing feature as if **curses\_trace** were called. **filter**, **initscr**, **new\_prescr**, **newterm**, **nofilter**, **restartterm**, **ripoffline**, **setupterm**, **slk\_init**, **tgetent**, **use\_env**, **use\_extended\_names**, **use\_tioctl** ## PORTABILITY These functions are not part of the X/Open Curses interface. Some other curses implementations are known to have similar features, but they are not compatible with *ncurses*: - • SVr4 provided **traceon** and **traceoff**, to control whether debugging information was written to the “trace” file. While the functions were always available, this feature was only enabled if **DEBUG** was defined when building the library. - The SVr4 tracing feature is undocumented. - • *PDCurses* provides **traceon** and **traceoff**, which (like SVr4) are always available, and enable tracing to the “trace” file only when a debug-library is built. - *PDCurses* has a short description of these functions, with a note that they are not present in X/Open Curses, *ncurses* or NetBSD. It does not mention SVr4, but the functions' inclusion in a header file section labeled “Quasi-standard” hints at the origin. - • NetBSD does not provide functions for enabling/disabling traces. It uses environment variables *CURSES\_TRACE\_MASK* and *CURSES\_TRACE\_FILE* to determine what is traced, and where the results are written. This is available only when a debug-library is built. - The NetBSD tracing feature is undocumented. A few *ncurses* functions are not provided when symbol versioning is used: \_nc\_tracebits, \_tracedump, \_tracemouse The original **trace** routine was deprecated because it often conflicted with application names. ## SEE ALSO **curses**(3X)