gh-144067: Document terminal leak when initscr() follows setupterm() (GH-152624)

The curses library keeps a single current terminal: calling initscr()
or newterm() after setupterm() abandons the terminal that setupterm()
allocated without freeing it.  This cannot be fixed safely in code
(freeing the terminal would break the capsule API and pending terminfo
queries), so document the behavior, with a cross-reference from
initscr() and newterm().

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index bbe29e5f46ed1de0e858cf8c922bc03cfed495c4..e413cd9d2bef2d90c9973459775d20bcf400265e 100644 (file)
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -76,6 +76,8 @@ Initialization and termination
    Initialize the library. Return a :ref:`window <curses-window-objects>` object
    which represents the whole screen.
 
+   See :func:`setupterm` for a caveat about calling it before this function.
+
    .. note::
 
       If there is an error opening the terminal, the underlying curses library may
@@ -106,6 +108,8 @@ Initialization and termination
    The new screen becomes the current one.
    Use :func:`set_term` to switch between screens.
 
+   See :func:`setupterm` for a caveat about calling it before this function.
+
    .. versionadded:: next
 
 .. function:: new_prescr()
@@ -959,6 +963,13 @@ Terminfo database
    terminfo database entry could not be read.  If the terminal has already
    been initialized, this function has no effect.
 
+   .. note::
+
+      Calling :func:`initscr` or :func:`newterm` after :func:`setupterm`
+      leaks the terminal that :func:`setupterm` allocated:
+      the curses library keeps only a single current terminal
+      and does not free the previously allocated one.
+
 .. function:: tigetflag(capname)
 
    Return the value of the Boolean capability corresponding to the terminfo