Document a workaround for a curses bug

abadger · abadger · commit 4138f2425be9 · 2019-05-12T14:17:51.000-07:00
The ncurses library has a bug which can provoke a segfault when a window is resized. The bug is provoked when a string with embedded newlines is added via addstr(). This commit documents that problem in the curses python library documentation and relates how to workaround the problem in the calling code. Related to https://bugs.python.org/issue35924
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
@@ -708,9 +708,16 @@ the following methods and attributes:
 
    .. note::
 
-      Writing outside the window, subwindow, or pad raises :exc:`curses.error`.
-      Attempting to write to the lower right corner of a window, subwindow,
-      or pad will cause an exception to be raised after the string is printed.
+      * Writing outside the window, subwindow, or pad raises :exc:`curses.error`.
+        Attempting to write to the lower right corner of a window, subwindow,
+        or pad will cause an exception to be raised after the string is printed.
+
+      * A `bug in ncurses <https://bugs.python.org/issue35924>`_, the backend
+        for this Python module, can cause SegFaults when resizing windows. This
+        is fixed in ncurses-6.1-20190511.  If you are stuck with an earlier
+        ncurses, you can avoid triggering this if you do not call :func:`addstr`
+        with a *str* that has embedded newlines.  Instead, call :func:`addstr`
+        separately for each line.
 
 
 .. method:: window.attroff(attr)
diff --git a/Misc/NEWS.d/next/Documentation/2019-05-08-13-17-44.bpo-35924.lqbNpW.rst b/Misc/NEWS.d/next/Documentation/2019-05-08-13-17-44.bpo-35924.lqbNpW.rst
@@ -0,0 +1,2 @@
+Add a note to the ``curses.addstr()`` documentation to warn that multiline
+strings can cause segfaults because of an ncurses bug.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Add a note to the ``curses.addstr()`` documentation to warn that multiline
	`2`	`+strings can cause segfaults because of an ncurses bug.`