X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_trace.3x;h=513340a362f4c2f56b1ebb5c62701db2b2ec5146;hp=ee9f19477b667793e5226261d00c67c84d644bac;hb=HEAD;hpb=74433bcf4f6fe40862a28f3c00edaedcd5054b01 diff --git a/man/curs_trace.3x b/man/curs_trace.3x index ee9f1947..ddae7911 100644 --- a/man/curs_trace.3x +++ b/man/curs_trace.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2019-2020,2021 Thomas E. Dickey * +.\" 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 * @@ -27,67 +27,76 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_trace.3x,v 1.24 2021/12/25 21:41:58 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\fP, -\fBtrace\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 \- \fBcurses\fP 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 \fP -.sp -\fBunsigned curses_trace(const unsigned \fP\fIparam\fP\fB);\fP -.sp -\fBvoid _tracef(const char *\fP\fIformat\fP\fB, ...);\fP -.sp -\fBchar *_traceattr(attr_t \fP\fIattr\fP\fB);\fP -.br -\fBchar *_traceattr2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fP -.br -\fBchar *_tracecchar_t(const cchar_t *\fP\fIstring\fP\fB);\fP -.br -\fBchar *_tracecchar_t2(int \fP\fIbuffer\fP\fB, const cchar_t *\fP\fIstring\fP\fB);\fP -.br -\fBchar *_tracechar(int \fP\fIch\fP\fB);\fP -.br -\fBchar *_tracechtype(chtype \fP\fIch\fP\fB);\fP -.br -\fBchar *_tracechtype2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fP -.sp -\fBvoid _tracedump(const char *\fP\fIlabel\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fP -.br -\fBchar *_nc_tracebits(void);\fP -.br -\fBchar *_tracemouse(const MEVENT *\fP\fIevent\fP\fB);\fP -.sp -/* deprecated */ -.br -\fBvoid trace(const unsigned int \fP\fIparam\fP\fB);\fP +.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 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, @@ -125,13 +134,13 @@ 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\fP definitions in \fB\fP. +values from the list of \fBTRACE_\fIxxx\fR definitions in \fB\fR. These include: .TP 5 .B TRACE_DISABLE @@ -194,31 +203,7 @@ 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) @@ -228,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\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 @@ -262,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, @@ -287,4 +298,4 @@ _tracemouse The original \fBtrace\fP routine was deprecated because it often conflicted with application names. .SH SEE ALSO -\fBcurses\fP(3X). +\fB\%curses\fP(3X)