X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_trace.3x;h=ddae7911254160565f7c286adde7bdc6b1657454;hb=refs%2Fheads%2Fmaster;hp=85df283c2c522716c294a3d2203da3e567c76334;hpb=c3b21f65a2687f3894a0d3217006c23f162c893a;p=ncurses.git diff --git a/man/curs_trace.3x b/man/curs_trace.3x index 85df283c..ddae7911 100644 --- a/man/curs_trace.3x +++ b/man/curs_trace.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 2000-2015,2016 Free Software Foundation, Inc. * +.\" Copyright 2019-2023,2024 Thomas E. Dickey * +.\" Copyright 2000-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -26,83 +27,135 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_trace.3x,v 1.14 2016/10/15 17:26:09 tom Exp $ +.\" $Id: curs_trace.3x,v 1.50 2024/04/20 21:24:19 tom Exp $ +.TH curs_trace 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. -.TH curs_trace 3X "" +. +.de dS \" Start unfilled display. +.nr aD \n(.j .na -.hy 0 +.. +. +.de dE \" End unfilled display. +.ad \n(.j +.rr aD +.. +. .SH NAME -\fB_tracef\fR, -\fB_tracedump\fR, -\fB_traceattr\fR, -\fB_traceattr2\fR, -\fB_nc_tracebits\fR, -\fB_tracecchar_t\fR, -\fB_tracecchar_t2\fR, -\fB_tracechar\fR, -\fB_tracechtype\fR, -\fB_tracechtype2\fR, -\fB_tracemouse\fR, -\fBtrace\fR \- \fBcurses\fR debugging routines -.ad -.hy +\fB\%curses_trace\fP, +\fB\%trace\fP, +\fB\%_tracef\fP, +\fB\%_traceattr\fP, +\fB\%_traceattr2\fP, +\fB\%_tracecchar_t\fP, +\fB\%_tracecchar_t2\fP, +\fB\%_tracechar\fP, +\fB\%_tracechtype\fP, +\fB\%_tracechtype2\fP, +\fB\%_nc_tracebits\fP, +\fB\%_tracedump\fP, +\fB\%_tracemouse\fP \- +\fIcurses\fR debugging routines .SH SYNOPSIS -\fB#include \fR -.sp -\fBvoid _tracef(const char *\fP\fIformat\fP\fB, ...);\fR -.br -\fBvoid _tracedump(const char *\fP\fIlabel\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fR -.br -\fBchar *_traceattr(attr_t \fP\fIattr\fP\fB);\fR -.br -\fBchar *_traceattr2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR -.br -\fBchar *_nc_tracebits(void);\fR -.br -\fBchar * _tracecchar_t(const cchar_t *\fP\fIstring\fP\fB);\fR -.br -\fBchar * _tracecchar_t2(int \fP\fIbuffer\fP\fB, const cchar_t *\fP\fIstring\fP\fB);\fR -.br -\fBchar *_tracechar(int \fP\fIch\fP\fB);\fR -.br -\fBchar *_tracechtype(chtype \fP\fIch\fP\fB);\fR -.br -\fBchar *_tracechtype2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR -.br -\fBchar *_tracemouse(const MEVENT *\fP\fIevent\fP\fB);\fR -.br -\fBvoid trace(const unsigned int \fP\fIparam\fP\fB);\fR -.SH DESCRIPTION -The \fBtrace\fR 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., \fIlibncurses_g.a\fR, but may be compiled into any model (shared, static, -profile) by defining the symbol \fBTRACE\fR. -Additionally, some functions are only available with the wide-character -configuration of the libraries. +.nf +\fB#include +.PP +\fBunsigned curses_trace(const unsigned \fItrace-mask\fP); +.PP +\fBvoid _tracef(const char *\fIformat\fP, ...); .PP +\fBchar *_traceattr(attr_t \fIattr\fP); +\fBchar *_traceattr2(int \fIbuffer\fP, chtype \fIch\fP); +\fBchar *_tracecchar_t(const cchar_t *\fIstring\fP); +\fBchar *_tracecchar_t2(int \fIbuffer\fP, const cchar_t *\fIstring\fP); +\fBchar *_tracechar(int \fIc\fP); +\fBchar *_tracechtype(chtype \fIch\fP); +\fBchar *_tracechtype2(int \fIbuffer\fP, chtype \fIch\fP); +.PP +\fBvoid _tracedump(const char *\fIlabel\fP, WINDOW *\fIwin\fP); +\fBchar *_nc_tracebits(void); +\fBchar *_tracemouse(const MEVENT *\fIevent\fP); +.PP +\fI/* deprecated */\fP +\fBvoid trace(const unsigned int \fItrace-mask\fP); +.fi +.SH DESCRIPTION +The \fIcurses trace\fP routines are used for debugging the +\fI\%ncurses\fP libraries, +as well as applications which use the \fI\%ncurses\fP libraries. +Some limitations apply: +.bP +Aside from \fBcurses_trace\fP, +the other functions are normally available only with the debugging library +e.g., \fBlibncurses_g.a\fP. +.IP +All of the trace functions may be compiled into any model (shared, static, +profile) by defining the symbol \fBTRACE\fP. +.bP +Additionally, the functions which use \fBcchar_t\fP +are only available with the wide-character configuration of the libraries. +.SS Functions The principal parts of this interface are .bP -\fBtrace\fR, which selectively enables different tracing features, and +\fBcurses_trace\fP, which selectively enables different tracing features, and .bP -\fB_tracef\fR, which writes formatted data to the \fItrace\fR file. +\fB_tracef\fP, which writes formatted data to the \fItrace\fP file. +.IP +The other functions either return a pointer to a string-area +(allocated by the corresponding function), or return no value +(such as \fB_tracedump\fP, +which implements the screen dump for \fBTRACE_UPDATE\fP). +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. .PP -Calling \fBtrace\fR with a nonzero parameter opens the file \fBtrace\fR -in the current directory for output. -The parameter is formed by OR'ing -values from the list of \fBTRACE_\fP\fIxxx\fR definitions in \fB\fR. +The \fBcurses_trace\fP function is always available, +whether or not the other trace functions are available: +.bP +If tracing is available, +calling \fBcurses_trace\fP with a nonzero parameter +updates the trace mask, +and returns the previous trace mask. +.IP +When the trace mask is nonzero, +\fI\%ncurses\fP creates the file \*(``trace\*('' in the current directory for output. +If the file already exists, no tracing is done. +.bP +If tracing is not available, \fBcurses_trace\fP returns zero (0). +.SS "Trace Parameter" +The trace parameter is formed by OR'ing +values from the list of \fBTRACE_\fIxxx\fR definitions in \fB\fR. These include: .TP 5 .B TRACE_DISABLE -turn off tracing. +turn off tracing by passing a zero parameter. +.IP +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 \fBcurses_trace\fP function. .TP 5 .B TRACE_TIMES trace user and system times of updates. .TP 5 .B TRACE_TPUTS -trace \fBtputs\fP calls. +trace \fBtputs\fP(3X) calls. .TP 5 .B TRACE_UPDATE trace update actions, old & new screens. @@ -123,7 +176,7 @@ trace all curses calls. The parameters for each call are traced, as well as return values. .TP 5 .B TRACE_VIRTPUT -trace virtual character puts, i.e., calls to \fBaddch\fR. +trace virtual character puts, i.e., calls to \fBaddch\fP. .TP 5 .B TRACE_IEVENT trace low-level input processing, including timeouts. @@ -146,48 +199,103 @@ trace changes to video attributes and colors. .B TRACE_MAXIMUM maximum trace level, enables all of the separate trace features. .PP -Some tracing features are enabled whenever the \fBtrace\fR parameter +Some tracing features are enabled whenever the \fBcurses_trace\fP parameter is nonzero. Some features overlap. The specific names are used as a guideline. +.SS "Command-line Utilities" +The command-line utilities such as \fBtic\fP(1) provide a verbose option +which extends the set of messages written using the \fBcurses_trace\fP function. +Both of these (\fB\-v\fP and \fBcurses_trace\fP) +use the same variable (\fB_nc_tracing\fP), +which determines the messages which are written. .PP -The other functions either return a pointer to a string-area -(allocated by the corresponding function), -or return no value (such as \fB_tracedump\fP, which implements the -screen dump for \fBTRACE_UPDATE\fP). -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. -.PP -These functions check the \fBNCURSES_TRACE\fP environment variable, -to set the tracing feature as if \fBtrace\fP was called: -.RS +Because the command-line utilities may call initialization functions +such as \fBsetupterm\fP, \fBtgetent\fP or \fBuse_extended_names\fP, +some of their debugging output may be directed to the \fItrace\fP file +if the \fI\%NCURSES_TRACE\fP environment variable is set: +.bP +messages produced in the utility are written to the standard error. +.bP +messages produced by the underlying library are written to \fItrace\fP. .PP -.na -filter, -initscr, -new_prescr, -newterm, -nofilter, -restartterm, -ripoffline, -setupterm, -slk_init, -tgetent, -use_env, -use_extended_names, -use_tioctl -.ad -.RE +If \fI\%ncurses\fP is built without tracing, +none of the latter are produced, +and fewer diagnostics are provided by the command-line utilities. .SH RETURN VALUE Routines which return a value are designed to be used as parameters -to the \fB_tracef\fR routine. +to the \fB_tracef\fP routine. +.SH ENVIRONMENT +.SS NCURSES_TRACE +A positive integral value stored in this variable causes the following +functions to enable the tracing feature as if +.B \%curses_trace +were called. +.PP +.dS +.RS 4 +\fB\%filter\fP, +\fB\%initscr\fP, +\fB\%new_prescr\fP, +\fB\%newterm\fP, +\fB\%nofilter\fP, +\fB\%restartterm\fP, +\fB\%ripoffline\fP, +\fB\%setupterm\fP, +\fB\%slk_init\fP, +\fB\%tgetent\fP, +\fB\%use_env\fP, +\fB\%use_extended_names\fP, +\fB\%use_tioctl\fP +.RE +.dE .SH PORTABILITY -These functions are not part of the XSI interface. +These functions are not part of the X/Open Curses interface. Some other curses implementations are known to -have similar, undocumented features, -but they are not compatible with ncurses. +have similar features, +but they are not compatible with \fI\%ncurses\fP: +.bP +SVr4 provided \fBtraceon\fP and \fBtraceoff\fP, +to control whether debugging information was written +to the \*(``trace\*('' file. +While the functions were always available, +this feature was only enabled +if \fBDEBUG\fP was defined when building the library. +.IP +The SVr4 tracing feature is undocumented. +.bP +PDCurses provides \fBtraceon\fP and \fBtraceoff\fP, +which (like SVr4) are always available, +and enable tracing +to the \*(``trace\*('' file +only when a debug-library is built. +.IP +PDCurses has a short description of these functions, +with a note that they are not present in X/Open Curses, +\fI\%ncurses\fP or NetBSD. +It does not mention SVr4, +but the functions' inclusion in a header file section +labeled \*(``Quasi-standard\*('' hints at the origin. +.bP +NetBSD does not provide functions for enabling/disabling traces. +It uses environment variables +\fI\%CURSES_TRACE_MASK\fP and +\fI\%CURSES_TRACE_FILE\fP to determine what is traced, +and where the results are written. +This is available only when a debug-library is built. +.IP +The NetBSD tracing feature is undocumented. +.PP +A few \fI\%ncurses\fP functions are not provided when symbol versioning +is used: +.RS 4 +.PP +_nc_tracebits, +_tracedump, +_tracemouse +.RE +.PP +The original \fBtrace\fP routine was deprecated because +it often conflicted with application names. .SH SEE ALSO -\fBcurses\fR(3X). +\fB\%curses\fP(3X)