X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_trace.3x;h=ddae7911254160565f7c286adde7bdc6b1657454;hb=HEAD;hp=186601c9785c4d4ae1b03c92e24054e196bee932;hpb=8890c8f28a1db5995ef17f52a7d8c0b9cf574210;p=ncurses.git diff --git a/man/curs_trace.3x b/man/curs_trace.3x index 186601c9..ddae7911 100644 --- a/man/curs_trace.3x +++ b/man/curs_trace.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 2000-2017,2019 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,84 +27,93 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_trace.3x,v 1.20 2019/12/07 18:55:02 tom Exp $ -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' +.\" $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 .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 -\fBcurses_trace\fR, -\fBtrace\fR, -\fB_tracef\fR, -\fB_traceattr\fR, -\fB_traceattr2\fR, -\fB_tracecchar_t\fR, -\fB_tracecchar_t2\fR, -\fB_tracechar\fR, -\fB_tracechtype\fR, -\fB_tracechtype2\fR, -\fB_nc_tracebits\fR, -\fB_tracedump\fR, -\fB_tracemouse\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 -\fBunsigned curses_trace(const unsigned \fP\fIparam\fP\fB);\fR -.sp -\fBvoid _tracef(const char *\fP\fIformat\fP\fB, ...);\fR -.sp -\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 *_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 -.sp -\fBvoid _tracedump(const char *\fP\fIlabel\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fR -.br -\fBchar *_nc_tracebits(void);\fR -.br -\fBchar *_tracemouse(const MEVENT *\fP\fIevent\fP\fB);\fR -.sp -/* deprecated */ -.br -\fBvoid trace(const unsigned int \fP\fIparam\fP\fB);\fR +.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\fR routines are used for debugging the ncurses libraries, -as well as applications which use the ncurses libraries. +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., \fIlibncurses_g.a\fR. +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\fR. +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 -\fBcurses_trace\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 @@ -115,22 +125,22 @@ 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 -The \fBcurses_trace\fR function is always available, +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\fR with a nonzero parameter +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, -ncurses creates the file \*(``trace\*('' in the current directory for output. +\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 +.SS "Trace Parameter" The trace parameter is formed by OR'ing -values from the list of \fBTRACE_\fP\fIxxx\fR definitions in \fB\fR. +values from the list of \fBTRACE_\fIxxx\fR definitions in \fB\fR. These include: .TP 5 .B TRACE_DISABLE @@ -166,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. @@ -189,35 +199,11 @@ 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 \fBcurses_trace\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 Initialization -These functions check the \fBNCURSES_TRACE\fP environment variable, -to set the tracing feature as if \fBcurses_trace\fP was called: -.RS 4 -.PP -.na -.hy 0 -filter, -initscr, -new_prescr, -newterm, -nofilter, -restartterm, -ripoffline, -setupterm, -slk_init, -tgetent, -use_env, -use_extended_names, -use_tioctl -.hy -.ad -.RE -.SS Command-line Utilities -.PP +.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) @@ -227,22 +213,47 @@ which determines the messages which are written. 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 \fBNCURSES_TRACE\fP environment variable is set: +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 -If ncurses is built without tracing, none of the latter are produced, +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 features, -but they are not compatible with ncurses: +but they are not compatible with \fI\%ncurses\fP: .bP SVr4 provided \fBtraceon\fP and \fBtraceoff\fP, to control whether debugging information was written @@ -261,21 +272,22 @@ 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, -ncurses or NetBSD. +\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 -\fBCURSES_TRACE_MASK\fP and -\fBCURSES_TRACE_FILE\fP to determine what is traced, +\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 ncurses functions are not provided when symbol versioning is used: +A few \fI\%ncurses\fP functions are not provided when symbol versioning +is used: .RS 4 .PP _nc_tracebits, @@ -286,4 +298,4 @@ _tracemouse The original \fBtrace\fP routine was deprecated because it often conflicted with application names. .SH SEE ALSO -\fBcurses\fR(3X). +\fB\%curses\fP(3X)