X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_memleaks.3x;h=59bd3e851f929c9a6aef5fefc7714040e3d7a390;hp=a8a455257f2d9405e79468ae2fbe59881b62371e;hb=61790aa3ac9e0dff2b443ac567b174fc4d235b86;hpb=e116460ef1091a4bbf0a97e04459d9b4f95b6165

diff --git a/man/curs_memleaks.3x b/man/curs_memleaks.3x
index a8a45525..59bd3e85 100644
--- a/man/curs_memleaks.3x
+++ b/man/curs_memleaks.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 2008 Free Software Foundation, Inc.                        *
+.\" Copyright 2019-2020,2021 Thomas E. Dickey                                *
+.\" Copyright 2008-2010,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,50 +27,80 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_memleaks.3x,v 1.1 2008/10/25 23:38:13 tom Exp $
+.\" $Id: curs_memleaks.3x,v 1.11 2021/01/02 23:47:51 tom Exp $
 .TH curs_memleaks 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
 .na
 .hy 0
 .SH NAME
-\fB_nc_freeall\fP
-\fB_nc_free_and_exit\fP - \fBcurses\fR memory-leak checking
+\fBexit_curses\fP,
+\fBexit_terminfo\fP \- \fBcurses\fR memory-leak checking
 .ad
 .hy
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
+.br
+\fBvoid exit_curses(int \fP\fIcode\fP\fB);\fR
+.sp
+\fB#include <term.h>\fR
+.br
+\fBvoid exit_terminfo(int \fP\fIcode\fP\fB);\fR
 .sp
+/* deprecated (intentionally not declared in curses.h or term.h) */
+.br
 \fBvoid _nc_freeall(void);\fR
 .br
-\fBvoid _nc_free_and_exit(int);\fR
+\fBvoid _nc_free_and_exit(int \fP\fIcode\fP\fB);\fR
+.br
+\fBvoid _nc_free_tinfo(int \fP\fIcode\fP\fB);\fR
 .SH DESCRIPTION
 These functions are used to simplify analysis of memory leaks in the ncurses
 library.
-They are normally not available; they must be configured into the library
-at build time using the \fB--disable-leaks\fP option.
-That compiles-in code that frees memory that normally would not be freed.
 .PP
 Any implementation of curses must not free the memory associated with
-a screen, since (even after calling \fBendwin\fP), it must be available
-for use in the next call to \fBrefresh\fP.
+a screen, since (even after calling \fBendwin\fP(3X)), it must be available
+for use in the next call to \fBrefresh\fP(3X).
 There are also chunks of memory held for performance reasons.
 That makes it hard to analyze curses applications for memory leaks.
-To work around this, one can build a debugging version of the ncurses
-library which frees those chunks which it can, and provides these
-functions to free all of the memory allocated by the ncurses library.
+When using the specially configured debugging version of the ncurses library,
+applications can call functions which free those chunks of memory,
+simplifying the process of memory-leak checking.
+.PP
+Some of the functions are named with a \*(``_nc_\*('' prefix
+because they are not intended for use in the non-debugging library:
+.TP 5
+\fB_nc_freeall\fP
+This frees (almost) all of the memory allocated by ncurses.
+.TP 5
+\fB_nc_free_and_exit\fP
+This frees the memory allocated by ncurses (like \fB_nc_freeall\fP),
+and exits the program.
+It is preferred over \fB_nc_freeall\fP since some of that memory
+may be required to keep the application running.
+Simply exiting (with the given exit-code) is safer.
+.TP 5
+\fB_nc_free_tinfo\fP
+Use this function if only the low-level terminfo functions (and
+corresponding library) are used.
+Like \fB_nc_free_and_exit\fP, it exits the program after freeing memory.
+.PP
+The functions prefixed \*(``_nc\*('' are normally not available;
+they must be configured into the library
+at build time using the \fB\-\-disable-leaks\fP option.
+That compiles-in code that frees memory that normally would not be freed.
 .PP
-The \fP_nc_free_and_exit\fP function is the preferred one since
-some of the memory which is freed may be required for the application
-to continue running.
-Its parameter is the code to pass to the \fPexit\fP routine.
+The \fBexit_curses\fP and \fBexit_terminfo\fP functions
+call \fB_nc_free_and_exit\fP and \fB_nc_free_tinfo\fP if
+the library is configured to support memory-leak checking.
+If the library is not configured to support memory-leak checking,
+they simply call \fBexit\fP.
 .SH RETURN VALUE
 These functions do not return a value.
 .SH PORTABILITY
-These functions are not part of the XSI interface.
+These functions are not part of X/Open Curses;
+nor do other implementations of curses provide a similar feature.
 .SH SEE ALSO
 \fBcurses\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: