---
name: "curs_trace"
section: "3x"
platform: "macos"
package: "ncurses"
version: "79"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/curs_trace/3x"
---

# curs\_trace(3x)

curses debugging routines

## NAME

**\_tracef**, **\_tracedump**, **\_traceattr**, **\_traceattr2**, **\_nc\_tracebits**, **\_tracecchar\_t**, **\_tracecchar\_t2**, **\_tracechar**, **\_tracechtype**, **\_tracechtype2**, **\_tracemouse**, **trace** - **curses** debugging routines

## SYNOPSIS

**#include \<curses.h\>**

**void \_tracef(const char \****format***, ...);**\
 **void \_tracedump(const char \****label***, WINDOW \****win***);**\
 **char \*\_traceattr(attr\_t** *attr***);**\
 **char \*\_traceattr2(int** *buffer***, chtype** *ch***);**\
 **char \*\_nc\_tracebits(void);**\
 **char \* \_tracecchar\_t(const cchar\_t \****string***);**\
 **char \* \_tracecchar\_t2(int** *buffer***, const cchar\_t \****string***);**\
 **char \*\_tracechar(int** *ch***);**\
 **char \*\_tracechtype(chtype** *ch***);**\
 **char \*\_tracechtype2(int** *buffer***, chtype** *ch***);**\
 **char \*\_tracemouse(const MEVENT \****event***);**\
 **void trace(const unsigned int** *param***);**

## DESCRIPTION

The **trace** 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 e.g., *libncurses\_g.a*, but may be compiled into any model (shared, static, profile) by defining the symbol **TRACE**. Additionally, some functions are only available with the wide-character configuration of the libraries.

The principal parts of this interface are

- •

  **trace**, which selectively enables different tracing features, and

- •

  **\_tracef**, which writes formatted data to the *trace* file.

Calling **trace** with a nonzero parameter opens the file **trace** in the current directory for output. The parameter is formed by OR'ing values from the list of **TRACE\_***xxx* definitions in **\<curses.h\>**. These include:

- **TRACE\_DISABLE**

  turn off tracing.

- **TRACE\_TIMES**

  trace user and system times of updates.

- **TRACE\_TPUTS**

  trace tputs 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 **trace** parameter is nonzero. Some features overlap. The specific names are used as a guideline.

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.

These functions check the **NCURSES\_TRACE** environment variable, to set the tracing feature as if **trace** was called:

filter, initscr, new\_prescr, newterm, nofilter, restartterm, ripoffline, setupterm, slk\_init, tgetent, use\_env, use\_extended\_names, use\_tioctl

## RETURN VALUE

Routines which return a value are designed to be used as parameters to the **\_tracef** routine.

## PORTABILITY

These functions are not part of the XSI interface. Some other curses implementations are known to have similar, undocumented features, but they are not compatible with ncurses.

## SEE ALSO

**curses**(3X).